@modelprofile.com/flexharness 8.2.0 → 8.4.0

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.2.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.2.0",
-    "@modelprofile.com/flexharness-models": "8.2.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.2.0',
+  version: '8.4.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }

package/ts/classes.flexharness.ts

@@ -16,6 +16,7 @@ import {
   FlexHarnessStoreCommitUncertainError,
   FlexHarnessValidationError,
   errorToInfo,
+  modelLimitErrorInfo,
 } from './errors.js';
 import {
   FLEX_PROJECT_MANAGEMENT_LIMITS,
@@ -79,6 +80,7 @@ import type {
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
+  IFlexSessionActivity,
   IFlexSessionGeneration,
   IFlexSessionGenerationCohortEntry,
   IFlexSessionReversionGroup,
@@ -97,6 +99,7 @@ import type {
   IFlexUndoSessionResult,
   IFlexUpdateSessionOptions,
   IFlexUpdateProjectTaskInput,
+  IFlexUsage,
   IJsonObject,
   TFlexAgentToolCallUpdateEvent,
   TFlexAgentToolCallFinishEvent,
@@ -335,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>;
@@ -658,6 +663,14 @@ function combineErrors(errors: unknown[]): unknown {
   return Object.freeze(combined);
 }
 
+/** The error and model limit a finished run leaves on its session activity. */
+function terminalActivityError(message: IFlexMessage): Pick<IFlexSessionActivity, 'error' | 'limit'> {
+  return {
+    ...(message.error ? { error: message.error } : {}),
+    ...(message.limit ? { limit: message.limit } : {}),
+  };
+}
+
 function isAbortError(error: unknown): boolean {
   return error instanceof FlexHarnessAbortError
     || (error instanceof DOMException && error.name === 'AbortError')
@@ -3386,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(),
@@ -3947,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;
@@ -5676,9 +5698,13 @@ export class FlexHarness<TScope = unknown> {
       }
       assistantMessage.usage = cloneSerializable(result.usage);
     } else {
+      assistantMessage.usage = cloneSerializable(run.usage);
       const message = truncateUtf8(error?.message ?? externalErrorFallback.message, maxTransferMetadataBytes);
-      userMessage.error = message;
-      assistantMessage.error = message;
+      const limit = error instanceof FlexHarnessExternalError ? error.limit : undefined;
+      for (const failedMessage of [userMessage, assistantMessage]) {
+        failedMessage.error = message;
+        if (limit) failedMessage.limit = cloneSerializable(limit);
+      }
     }
     return {
       runId: run.runId,
@@ -5692,7 +5718,7 @@ export class FlexHarness<TScope = unknown> {
             finishReason: result.finishReason,
             steps: result.steps,
           }
-        : {}),
+        : { usage: cloneSerializable(run.usage) }),
     };
   }
 
@@ -6766,7 +6792,7 @@ export class FlexHarness<TScope = unknown> {
         status: activityStatus,
         startedAt: run.stored.session.activity.startedAt,
         completedAt: timestamp,
-        ...(terminal.assistantMessage.error ? { error: terminal.assistantMessage.error } : {}),
+        ...terminalActivityError(terminal.assistantMessage),
       };
       run.stored.session.updatedAt = timestamp;
     }, true);
@@ -7025,6 +7051,63 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private onRetry(state: IStorageState, sessionId: string, retry: plugins.IAgentRetryEvent): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || !this.reserveCallbackCapacity(run, 1, 0, 0)) return;
+    this.emitEvent(run.scopeId, run.stored.session, {
+      type: 'run.retrying',
+      runId: run.runId,
+      attempt: retry.attempt,
+      maxAttempts: retry.maxAttempts,
+      delayMs: retry.delayMs,
+      reason: retry.reason,
+    });
+  }
+
+  /**
+   * 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;
@@ -7777,7 +7860,8 @@ export class FlexHarness<TScope = unknown> {
     if ((typeof error === 'object' && error !== null) && this.trustedInternalErrors.has(error)) {
       return error as Error;
     }
-    let info = externalErrorFallback;
+    const defaultInfo = modelLimitErrorInfo(error) ?? externalErrorFallback;
+    let info = defaultInfo;
     if (this.externalErrorProjector) {
       try {
         info = validateProjectedErrorInfo(this.externalErrorProjector(error, {
@@ -7787,7 +7871,7 @@ export class FlexHarness<TScope = unknown> {
           runId,
         }));
       } catch {
-        info = externalErrorFallback;
+        info = defaultInfo;
       }
     }
     return this.trustInternalError(new FlexHarnessExternalError(info));
@@ -8233,6 +8317,8 @@ export class FlexHarness<TScope = unknown> {
         onToolCallStart: (event) => this.onToolStart(state, sessionId, event),
         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,
@@ -8405,9 +8491,7 @@ export class FlexHarness<TScope = unknown> {
         runId: latestTerminal.runId,
         status: latestTerminal.status === 'completed' ? 'idle' : latestTerminal.status,
         completedAt,
-        ...(latestTerminal.assistantMessage.error
-          ? { error: latestTerminal.assistantMessage.error }
-          : {}),
+        ...terminalActivityError(latestTerminal.assistantMessage),
       };
       stored.session.updatedAt = completedAt;
     } else if (['scheduled', 'running', 'waiting_permission'].includes(stored.session.status)) {
@@ -8490,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,
@@ -8498,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/errors.ts

@@ -1,4 +1,10 @@
-import type { IFlexErrorInfo } from './interfaces.js';
+import * as plugins from './plugins.js';
+import type { IFlexErrorInfo, TFlexModelLimit } from './interfaces.js';
+
+const modelLimitErrorCodes: Record<TFlexModelLimit['kind'], string> = {
+  usage_limit: 'FLEX_USAGE_LIMIT',
+  rate_limit: 'FLEX_RATE_LIMIT',
+};
 
 export class FlexHarnessError extends Error {
   public readonly code: string;
@@ -85,9 +91,12 @@ export class FlexHarnessCallbackOverflowError extends FlexHarnessError {
 }
 
 export class FlexHarnessExternalError extends FlexHarnessError {
+  public readonly limit: TFlexModelLimit | undefined;
+
   constructor(info: IFlexErrorInfo) {
     super(info.code ?? 'FLEX_EXTERNAL_ERROR', info.message);
     this.name = info.name;
+    this.limit = info.limit;
   }
 }
 
@@ -164,6 +173,7 @@ export function errorToInfo(error: unknown): IFlexErrorInfo {
       name: error.name,
       message: error.message,
       code: error.code,
+      ...(error instanceof FlexHarnessExternalError && error.limit ? { limit: error.limit } : {}),
     };
   }
   if (error instanceof Error) {
@@ -179,6 +189,17 @@ export function errorToInfo(error: unknown): IFlexErrorInfo {
   };
 }
 
+/** The public projection of a model limit error, which names the limit and its reset time. */
+export function modelLimitErrorInfo(error: unknown): IFlexErrorInfo | undefined {
+  if (!plugins.isModelLimitError(error)) return undefined;
+  return {
+    name: 'FlexHarnessExternalError',
+    message: error.message,
+    code: modelLimitErrorCodes[error.limit.kind],
+    limit: error.limit,
+  };
+}
+
 export function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/ts/interfaces.ts

@@ -22,6 +22,15 @@ export type TFlexAgentToolCallUpdateEvent = Parameters<
 export type TFlexAgentToolCallFinishEvent = Parameters<
   NonNullable<TFlexAgentSessionOptions['onToolCallFinish']>
 >[0];
+/** 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';
@@ -123,8 +132,15 @@ 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. */
+  limit?: TFlexModelLimit;
 }
 
 export interface IFlexSessionActivity {
@@ -133,6 +149,8 @@ export interface IFlexSessionActivity {
   startedAt?: string;
   completedAt?: string;
   error?: string;
+  /** The model limit that failed the last run, next to its error. */
+  limit?: TFlexModelLimit;
 }
 
 export interface IFlexSession {
@@ -457,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;
@@ -1227,6 +1246,28 @@ export interface IFlexRunFinishedEvent extends IFlexEventBase {
   readonly error?: IFlexErrorInfo;
 }
 
+/** The run waits `delayMs` before retrying a rate-limited or unavailable model call. */
+export interface IFlexRunRetryingEvent extends IFlexEventBase {
+  readonly type: 'run.retrying';
+  readonly runId: string;
+  readonly attempt: number;
+  readonly maxAttempts: number;
+  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;
@@ -1244,6 +1285,8 @@ export interface IFlexErrorInfo {
   name: string;
   message: string;
   code?: string;
+  /** Set when a model usage or rate limit caused the error. */
+  limit?: TFlexModelLimit;
 }
 
 export type TFlexHarnessEvent =
@@ -1256,6 +1299,8 @@ export type TFlexHarnessEvent =
   | IFlexPermissionRequestedEvent
   | IFlexPermissionResolvedEvent
   | IFlexRunFinishedEvent
+  | IFlexRunRetryingEvent
+  | TFlexModelUsageEvent
   | IFlexPromptQueueEvent
   | IFlexSessionHistoryChangedEvent;
 

package/ts/plugins.ts

@@ -44,6 +44,7 @@ export type {
   IAgentGenerateResult,
   IAgentGenerationHandle,
   IAgentGenerationLease,
+  IAgentRetryEvent,
   IAgentRunResult,
   IAgentSession,
   IAgentSessionOptions,
@@ -62,6 +63,14 @@ export type {
   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/ts/utils.json.ts

@@ -1,3 +1,4 @@
+import * as plugins from './plugins.js';
 import { FlexHarnessStoreFormatError, FlexHarnessValidationError } from './errors.js';
 import {
   FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
@@ -406,6 +407,12 @@ function requireOptionalString(value: unknown, path: string): string | undefined
   return value === undefined ? undefined : requireString(value, path);
 }
 
+function requireOptionalModelLimit(value: unknown, path: string): void {
+  if (value !== undefined && !plugins.isModelLimitInfo(value)) {
+    throw new FlexHarnessStoreFormatError(`${path} is invalid.`);
+  }
+}
+
 function requireNonNegativeNumber(value: unknown, path: string): void {
   if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
     throw new FlexHarnessStoreFormatError(`${path} must be a non-negative finite number.`);
@@ -501,7 +508,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
   }
   const activity = requireRecord(session.activity, `${path}.activity`);
-  requireOnlyKeys(activity, ['runId', 'status', 'startedAt', 'completedAt', 'error'], `${path}.activity`);
+  requireOnlyKeys(activity, ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit'], `${path}.activity`);
   if (!activityStatuses.includes(activity.status as (typeof activityStatuses)[number])) {
     throw new FlexHarnessStoreFormatError(`${path}.activity.status is invalid.`);
   }
@@ -509,6 +516,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   requireOptionalString(activity.startedAt, `${path}.activity.startedAt`);
   requireOptionalString(activity.completedAt, `${path}.activity.completedAt`);
   requireOptionalString(activity.error, `${path}.activity.error`);
+  requireOptionalModelLimit(activity.limit, `${path}.activity.limit`);
   const relationship = [
     session.parentSessionId,
     session.parentRunId,
@@ -667,6 +675,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       'model',
       'usage',
       'error',
+      'limit',
     ],
     path,
   );
@@ -682,6 +691,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
   requireString(message.createdAt, `${path}.createdAt`);
   requireOptionalString(message.completedAt, `${path}.completedAt`);
   requireOptionalString(message.error, `${path}.error`);
+  requireOptionalModelLimit(message.limit, `${path}.limit`);
   if (message.model !== undefined) validateModel(message.model, `${path}.model`);
   if (message.usage !== undefined) validateUsage(message.usage, `${path}.usage`);
   if (!Array.isArray(message.parts)) {

package/ts/utils.validation.ts

@@ -1,3 +1,4 @@
+import * as plugins from './plugins.js';
 import { FlexHarnessValidationError } from './errors.js';
 import {
   FLEX_PROJECT_MANAGEMENT_LIMITS,
@@ -162,30 +163,30 @@ export function validateDeleteSessionGenerationCohortInput(
   return { root, authorizedBySessionId };
 }
 
-export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
+/** A plain object whose own properties are all string-keyed data properties, so reading them runs no code. */
+function isPlainDataObject(value: unknown): value is Record<string, unknown> {
   if (
     !value
     || typeof value !== 'object'
     || Array.isArray(value)
     || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
-  ) {
+  ) return false;
+  return Reflect.ownKeys(value).every((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return typeof key === 'string' && descriptor !== undefined && 'value' in descriptor;
+  });
+}
+
+export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
+  if (!isPlainDataObject(value)) {
     throw new FlexHarnessValidationError('External error projection is invalid.');
   }
-  const descriptors = Object.getOwnPropertyDescriptors(value);
-  const unsupportedKey = Reflect.ownKeys(descriptors).find(
-    (key) => typeof key !== 'string' || !['name', 'message', 'code'].includes(key),
-  );
-  const name = descriptors.name?.value;
-  const message = descriptors.message?.value;
-  const code = descriptors.code?.value;
+  const unsupportedKey = Object.getOwnPropertyNames(value)
+    .find((key) => !['name', 'message', 'code', 'limit'].includes(key));
+  const { name, message, code, limit } = value;
   if (
     unsupportedKey
-    || descriptors.name?.get !== undefined
-    || descriptors.name?.set !== undefined
-    || descriptors.message?.get !== undefined
-    || descriptors.message?.set !== undefined
-    || descriptors.code?.get !== undefined
-    || descriptors.code?.set !== undefined
+    || (limit !== undefined && !(isPlainDataObject(limit) && plugins.isModelLimitInfo(limit)))
     || typeof name !== 'string'
     || !name
     || Buffer.byteLength(name, 'utf8') > maxProjectedErrorNameBytes
@@ -199,7 +200,12 @@ export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
   ) {
     throw new FlexHarnessValidationError('External error projection is invalid.');
   }
-  return Object.freeze({ name, message, ...(code === undefined ? {} : { code }) });
+  return Object.freeze({
+    name,
+    message,
+    ...(code === undefined ? {} : { code }),
+    ...(limit === undefined ? {} : { limit: Object.freeze({ ...limit }) }),
+  });
 }
 
 export function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions): void {

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';