@modelprofile.com/flexharness 10.24.0 → 10.24.1

package/ts/classes.flexharness.admission.ts

@@ -0,0 +1,331 @@
+import { FlexHarnessAbortError, FlexHarnessValidationError } from './errors.js';
+import type {
+  IFlexDelegatedRunAdmissionLease,
+  IFlexSession,
+  IFlexSubagentDefinition,
+  IFlexToolMessagePart,
+} from './interfaces.js';
+import type {
+  IStoredSessionState,
+  IStorageState,
+  IActiveRun,
+  IDelegatedRunAdmissionSeed,
+  IDelegatedRunAdmissionOwner,
+  IQueuedPrompt,
+} from './interfaces.flexharness.js';
+import { requireSessionGeneration } from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** Admission of delegated runs through the delegated run admission provider. */
+export class FlexHarnessDelegatedRunAdmission<TScope> {
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public assertDelegatedRunAdmissionOwnership(
+    seed: IDelegatedRunAdmissionSeed,
+    state: IStorageState,
+    childStored: IStoredSessionState,
+    scopeId: string,
+  ): void {
+    const child = childStored.session;
+    const parentRun = seed.parentRun;
+    const parent = seed.parentStored.session;
+    const parentPartId = parentRun.toolPartIds.get(seed.parentToolCallId);
+    const parentPart = parentRun.callbackParts.find((part): part is IFlexToolMessagePart =>
+      part.type === 'tool'
+      && part.partId === parentPartId
+      && part.toolCallId === seed.parentToolCallId);
+    if (
+      seed.state !== state
+      || seed.storageKey !== state.storageKey
+      || seed.scopeId !== scopeId
+      || seed.childStored !== childStored
+      || childStored.storageKey !== seed.storageKey
+      || state.sessions.get(seed.sessionId) !== childStored
+      || state.tombstones.has(seed.sessionId)
+      || state.initializingSessions.has(seed.sessionId)
+      || child.sessionId !== seed.sessionId
+      || child.sessionGenerationId !== seed.sessionGenerationId
+      || child.sessionGenerationSequence !== seed.sessionGenerationSequence
+      || child.parentSessionId !== seed.parentSessionId
+      || child.parentRunId !== seed.originParentRunId
+      || child.parentToolCallId !== seed.originParentToolCallId
+      || child.agent !== seed.agent
+      || child.depth !== seed.depth
+      || seed.parentStored !== parentRun.stored
+      || seed.parentStored.storageKey !== seed.storageKey
+      || parentRun.state !== state
+      || parentRun.scopeId !== seed.scopeId
+      || parentRun.scope !== seed.scope
+      || parentRun.sessionId !== seed.parentSessionId
+      || parentRun.queueId !== seed.parentQueueId
+      || parentRun.runId !== seed.parentRunId
+      || state.sessions.get(seed.parentSessionId) !== seed.parentStored
+      || state.tombstones.has(seed.parentSessionId)
+      || parent.sessionId !== seed.parentSessionId
+      || parent.sessionGenerationId !== seed.parentSessionGenerationId
+      || parent.sessionGenerationSequence !== seed.parentSessionGenerationSequence
+      || state.activeRuns.get(seed.parentSessionId) !== parentRun
+      || parentRun.callbacksClosed
+      || parentRun.controller.signal.aborted
+      || parentPart?.status !== 'running'
+    ) {
+      throw this.core.trustInternalError(
+        new FlexHarnessAbortError('The delegated prompt lost its exact parent or child ownership.'),
+      );
+    }
+  }
+
+  public async acquireDelegatedRunAdmission(
+    queued: IQueuedPrompt,
+    run: IActiveRun,
+  ): Promise<void> {
+    const seed = queued.delegationSeed;
+    const provider = this.core.delegatedRunAdmissionProvider;
+    if (!seed || !provider) return;
+    const context = Object.freeze({
+      scopeId: seed.scopeId,
+      scope: seed.scope as TScope,
+      storageKey: seed.storageKey,
+      sessionId: seed.sessionId,
+      sessionGenerationId: seed.sessionGenerationId,
+      sessionGenerationSequence: seed.sessionGenerationSequence,
+      queueId: queued.queueId,
+      runId: run.runId,
+      parentSessionId: seed.parentSessionId,
+      parentSessionGenerationId: seed.parentSessionGenerationId,
+      parentSessionGenerationSequence: seed.parentSessionGenerationSequence,
+      parentQueueId: seed.parentQueueId,
+      parentRunId: seed.parentRunId,
+      parentToolCallId: seed.parentToolCallId,
+      originParentRunId: seed.originParentRunId,
+      originParentToolCallId: seed.originParentToolCallId,
+      agent: seed.agent,
+      depth: seed.depth,
+      signal: run.controller.signal,
+    });
+    const owner: IDelegatedRunAdmissionOwner = {
+      storageState: run.state,
+      run,
+      context,
+      status: 'acquiring',
+      acquisitionSettled: false,
+      acquisitionDetached: false,
+      closeAttemptSequence: 0,
+    };
+    run.state.delegatedRunAdmissionOwners.add(owner);
+    run.delegatedRunAdmissionOwner = owner;
+    const acquisition = Promise.resolve()
+      .then(() => provider.acquireDelegatedRunAdmission(context))
+      .then((lease) => this.normalizeDelegatedRunAdmissionLease(lease))
+      .then(
+        (lease) => {
+          owner.lease = lease;
+          owner.acquisitionSettled = true;
+          if (owner.status === 'acquiring') owner.status = 'acquired';
+          if (owner.status === 'close-requested') {
+            void this.startDelegatedRunAdmissionCloseAttempt(owner).catch(() => undefined);
+          }
+        },
+        (error: unknown) => {
+          owner.acquisitionError = this.core.projectExternalError(
+            run,
+            error,
+            'delegatedRunAdmissionProvider',
+          );
+          owner.acquisitionSettled = true;
+          owner.status = 'closed';
+          run.state.delegatedRunAdmissionOwners.delete(owner);
+        },
+      );
+    owner.acquisitionCompletion = acquisition;
+
+    let resolveAbort!: () => void;
+    const abort = new Promise<'aborted'>((resolve) => {
+      resolveAbort = () => resolve('aborted');
+    });
+    run.controller.signal.addEventListener('abort', resolveAbort, { once: true });
+    if (run.controller.signal.aborted) resolveAbort();
+    try {
+      const outcome = await Promise.race([
+        acquisition.then(() => 'settled' as const),
+        abort,
+      ]);
+      if (outcome === 'aborted') {
+        owner.acquisitionDetached = true;
+        throw run.controller.signal.reason ?? this.core.trustInternalError(new FlexHarnessAbortError());
+      }
+      if (run.controller.signal.aborted) {
+        throw run.controller.signal.reason ?? this.core.trustInternalError(new FlexHarnessAbortError());
+      }
+      if (owner.acquisitionError) throw owner.acquisitionError;
+      if (owner.status !== 'acquired' || !owner.lease) {
+        throw this.core.trustInternalError(
+          new FlexHarnessAbortError('The delegated run admission was retired during acquisition.'),
+        );
+      }
+    } finally {
+      run.controller.signal.removeEventListener('abort', resolveAbort);
+    }
+  }
+
+  private normalizeDelegatedRunAdmissionLease(
+    value: IFlexDelegatedRunAdmissionLease,
+  ): IFlexDelegatedRunAdmissionLease {
+    if (!value || (typeof value !== 'object' && typeof value !== 'function')) {
+      throw new FlexHarnessValidationError(
+        'Delegated run admission provider returned an invalid lease.',
+      );
+    }
+    const close = value.close;
+    if (typeof close !== 'function') {
+      throw new FlexHarnessValidationError(
+        'Delegated run admission provider returned an invalid lease.',
+      );
+    }
+    return Object.freeze({ close: () => close.call(value) });
+  }
+
+  private requestDelegatedRunAdmissionClose(
+    owner: IDelegatedRunAdmissionOwner,
+  ): Promise<void> {
+    const priorAttemptSequence = owner.closeAttemptSequence;
+    const joinedAttempt = owner.closeAttempt;
+    if (owner.status === 'closed') return Promise.resolve();
+    if (owner.status !== 'retrying') owner.status = 'close-requested';
+    return (async () => {
+      await owner.acquisitionCompletion;
+      if (owner.status === 'closed') return;
+      if (joinedAttempt) {
+        await joinedAttempt;
+        return;
+      }
+      if (owner.closeAttempt) {
+        await owner.closeAttempt;
+        return;
+      }
+      if (owner.closeFailure && owner.closeFailure.sequence > priorAttemptSequence) {
+        throw owner.closeFailure.error;
+      }
+      await this.startDelegatedRunAdmissionCloseAttempt(owner);
+    })();
+  }
+
+  private startDelegatedRunAdmissionCloseAttempt(
+    owner: IDelegatedRunAdmissionOwner,
+  ): Promise<void> {
+    if (owner.closeAttempt) return owner.closeAttempt;
+    if (!owner.lease) {
+      throw new Error('Acquired delegated run admission has no lease.');
+    }
+    owner.status = 'retrying';
+    owner.closeFailure = undefined;
+    const sequence = ++owner.closeAttemptSequence;
+    let attempt!: Promise<void>;
+    attempt = Promise.resolve()
+      .then(() => owner.lease!.close())
+      .then(() => {
+        owner.status = 'closed';
+        delete owner.lease;
+        owner.storageState.delegatedRunAdmissionOwners.delete(owner);
+      }, (error: unknown) => {
+        const projected = this.core.projectExternalError(
+          owner.run,
+          error,
+          'delegatedRunAdmissionProvider',
+        );
+        owner.closeFailure = { sequence, error: projected };
+        owner.status = 'close-requested';
+        throw projected;
+      })
+      .finally(() => {
+        if (owner.closeAttempt === attempt) owner.closeAttempt = undefined;
+      });
+    owner.closeAttempt = attempt;
+    return attempt;
+  }
+
+  public async closeRunDelegatedRunAdmission(
+    run: IActiveRun,
+    awaitSettlement = true,
+  ): Promise<void> {
+    const owner = run.delegatedRunAdmissionOwner;
+    if (!owner) return;
+    if (!run.delegatedRunAdmissionClose) {
+      run.delegatedRunAdmissionClose = this.requestDelegatedRunAdmissionClose(owner);
+      void run.delegatedRunAdmissionClose.catch(() => undefined);
+    }
+    if (awaitSettlement) await run.delegatedRunAdmissionClose;
+  }
+
+  public createDelegatedRunAdmissionSeed(
+    run: IActiveRun,
+    child: IStoredSessionState,
+    definition: Readonly<IFlexSubagentDefinition>,
+    toolCallId: string,
+  ): IDelegatedRunAdmissionSeed {
+    const childGeneration = requireSessionGeneration(child.session);
+    const parentGeneration = requireSessionGeneration(run.stored.session);
+    if (!child.session.parentRunId || !child.session.parentToolCallId) {
+      throw new FlexHarnessValidationError('Subagent session origin metadata is missing.');
+    }
+    const seed = Object.freeze({
+      state: run.state,
+      childStored: child,
+      parentRun: run,
+      parentStored: run.stored,
+      scopeId: run.scopeId,
+      scope: run.scope,
+      storageKey: run.state.storageKey,
+      sessionId: child.session.sessionId,
+      ...childGeneration,
+      originParentRunId: child.session.parentRunId,
+      originParentToolCallId: child.session.parentToolCallId,
+      parentSessionId: run.sessionId,
+      parentSessionGenerationId: parentGeneration.sessionGenerationId,
+      parentSessionGenerationSequence: parentGeneration.sessionGenerationSequence,
+      parentQueueId: run.queueId,
+      parentRunId: run.runId,
+      parentToolCallId: toolCallId,
+      ...(run.stored.session.configurationRef === undefined
+        ? {}
+        : { configurationRef: run.stored.session.configurationRef }),
+      agent: definition.name,
+      depth: (run.stored.session.depth ?? 0) + 1,
+    });
+    this.assertDelegatedRunAdmissionOwnership(seed, run.state, child, run.scopeId);
+    return seed;
+  }
+
+  public delegatedRunAdmissionOwnersForGeneration(
+    state: IStorageState,
+    session: Readonly<Pick<
+      IFlexSession,
+      'sessionId' | 'sessionGenerationId' | 'sessionGenerationSequence'
+    >>,
+  ): IDelegatedRunAdmissionOwner[] {
+    return [...state.delegatedRunAdmissionOwners].filter((owner) =>
+      owner.storageState === state
+      && owner.context.sessionId === session.sessionId
+      && owner.context.sessionGenerationId === session.sessionGenerationId
+      && owner.context.sessionGenerationSequence === session.sessionGenerationSequence);
+  }
+
+  public async settleDelegatedRunAdmissionOwners(
+    owners: readonly IDelegatedRunAdmissionOwner[],
+  ): Promise<Error[]> {
+    const results = await Promise.allSettled(
+      owners.map((owner) => this.requestDelegatedRunAdmissionClose(owner)),
+    );
+    return results.flatMap((result, index) => {
+      if (result.status === 'fulfilled') return [];
+      const error = result.reason instanceof Error
+        ? result.reason
+        : this.core.projectExternalError(
+            owners[index].run,
+            result.reason,
+            'delegatedRunAdmissionProvider',
+          );
+      return [error];
+    });
+  }
+}

package/ts/classes.flexharness.callbacks.ts

@@ -0,0 +1,352 @@
+import * as plugins from './plugins.js';
+import { FlexHarnessCallbackOverflowError } from './errors.js';
+import {
+  FLEX_TOOL_CATALOG_TOOL_NAMES,
+  type IFlexReasoningMessagePart,
+  type IFlexToolMessagePart,
+  type IFlexUsage,
+  type TFlexAgentToolCallUpdateEvent,
+  type TFlexAgentToolCallFinishEvent,
+  type TFlexMessagePart,
+} from './interfaces.js';
+import { normalizeJsonValue } from './utils.json.js';
+import { jsonBytes } from './utils.transfer.js';
+import {
+  observeSessionMetricsCall,
+  settleSessionMetricsOperation,
+  type ISessionMetricsOperation,
+} from './utils.sessionmetrics.js';
+import type { IStoredSessionState, IStorageState, IActiveRun } from './interfaces.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** The model stream callbacks of a run: text, reasoning, tool, retry and usage events. */
+export class FlexHarnessRunCallbacks<TScope> {
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public onTextDelta(state: IStorageState, sessionId: string, delta: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || !delta) return;
+    const lastPart = run.callbackParts.at(-1);
+    const created = lastPart?.type !== 'text';
+    const part = lastPart?.type === 'text'
+      ? lastPart
+      : { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: '' };
+    const accounting = this.textAppendAccounting(run, part, delta, created);
+    if (!accounting) return;
+    if (!this.reserveCallbackCapacity(
+      run,
+      created ? 2 : 1,
+      accounting.textUtf8Bytes - accounting.baseTextUtf8Bytes,
+      created ? 1 : 0,
+    )) return;
+    if (created) {
+      run.callbackParts.push(part);
+      run.partTextUtf8Bytes.set(part.partId, 0);
+      this.core.emitPartEvent(run, 'part.started', part);
+    }
+    part.text += delta;
+    run.partTextUtf8Bytes.set(part.partId, accounting.textUtf8Bytes);
+    this.core.emitPartDeltaEvent(run, part, delta, accounting);
+  }
+
+  public onReasoningStart(state: IStorageState, sessionId: string, id: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || run.reasoningPartIds.has(id)) return;
+    if (!this.reserveCallbackCapacity(run, 1, 0, 1)) return;
+    const part: IFlexReasoningMessagePart = {
+      partId: plugins.crypto.randomUUID(),
+      type: 'reasoning',
+      text: '',
+      status: 'running',
+      startedAt: new Date().toISOString(),
+    };
+    run.reasoningPartIds.set(id, part.partId);
+    run.callbackParts.push(part);
+    run.partTextUtf8Bytes.set(part.partId, 0);
+    this.core.emitPartEvent(run, 'part.started', part);
+  }
+
+  public onReasoningDelta(state: IStorageState, sessionId: string, id: string, delta: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || !delta) return;
+    if (!run.reasoningPartIds.has(id)) this.onReasoningStart(state, sessionId, id);
+    const partId = run.reasoningPartIds.get(id);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'reasoning');
+    if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
+    const accounting = this.textAppendAccounting(run, part, delta);
+    if (!accounting) return;
+    if (!this.reserveCallbackCapacity(
+      run,
+      1,
+      accounting.textUtf8Bytes - accounting.baseTextUtf8Bytes,
+      0,
+    )) return;
+    part.text += delta;
+    run.partTextUtf8Bytes.set(part.partId, accounting.textUtf8Bytes);
+    this.core.emitPartDeltaEvent(run, part, delta, accounting);
+  }
+
+  public onReasoningEnd(state: IStorageState, sessionId: string, id: string, text: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    if (!run.reasoningPartIds.has(id)) this.onReasoningStart(state, sessionId, id);
+    const partId = run.reasoningPartIds.get(id);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'reasoning');
+    if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
+    const missingText = part.text ? '' : text;
+    const missingTextUtf8Bytes = Buffer.byteLength(missingText, 'utf8');
+    if (!this.reserveCallbackCapacity(run, 1, missingTextUtf8Bytes, 0)) return;
+    if (missingText) {
+      part.text = missingText;
+      run.partTextUtf8Bytes.set(part.partId, missingTextUtf8Bytes);
+    }
+    part.status = 'completed';
+    part.completedAt = new Date().toISOString();
+    this.core.emitPartEvent(run, 'part.completed', part);
+  }
+
+  private textAppendAccounting(
+    run: IActiveRun,
+    part: Extract<TFlexMessagePart, { type: 'text' | 'reasoning' }>,
+    delta: string,
+    created = false,
+  ): { baseTextUtf8Bytes: number; textUtf8Bytes: number } | undefined {
+    const baseTextUtf8Bytes = created ? 0 : run.partTextUtf8Bytes.get(part.partId);
+    if (baseTextUtf8Bytes === undefined) {
+      throw new Error('Flex part text byte accounting is unavailable.');
+    }
+    const trailingCodeUnit = part.text.charCodeAt(part.text.length - 1);
+    const leadingCodeUnit = delta.charCodeAt(0);
+    const joinsSurrogatePair = trailingCodeUnit >= 0xD800
+      && trailingCodeUnit <= 0xDBFF
+      && leadingCodeUnit >= 0xDC00
+      && leadingCodeUnit <= 0xDFFF;
+    const textUtf8Bytes = baseTextUtf8Bytes
+      + Buffer.byteLength(delta, 'utf8')
+      - (joinsSurrogatePair ? 2 : 0);
+    if (!Number.isSafeInteger(textUtf8Bytes)) {
+      this.failCallback(run, this.core.trustInternalError(new FlexHarnessCallbackOverflowError(
+        'Callback text byte accounting exceeded the safe integer range.',
+      )));
+      return undefined;
+    }
+    return { baseTextUtf8Bytes, textUtf8Bytes };
+  }
+
+  public onToolStart(
+    state: IStorageState,
+    sessionId: string,
+    event: { toolCallId: string; toolName: string; input: unknown; parentToolCallId?: string },
+  ): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || run.toolPartIds.has(event.toolCallId)) return;
+    try {
+      // An execute call is the call of the catalog method it names.
+      const target = event.toolName === FLEX_TOOL_CATALOG_TOOL_NAMES.execute
+        ? run.toolCatalog?.callTarget(event.input)
+        : undefined;
+      const input = normalizeJsonValue(target ? target.params : event.input, this.core.toolOutputLimits);
+      if (!this.reserveCallbackCapacity(run, 1, jsonBytes(input), 1)) return;
+      const part: IFlexToolMessagePart = {
+        partId: plugins.crypto.randomUUID(),
+        type: 'tool',
+        toolCallId: this.core.boundedIdentifier(event.toolCallId, 'toolCallId'),
+        toolName: this.core.boundedIdentifier(target ? target.method : event.toolName, 'toolName'),
+        status: 'running',
+        input,
+        ...(event.parentToolCallId === undefined
+          ? {}
+          : { parentToolCallId: this.core.boundedIdentifier(event.parentToolCallId, 'parentToolCallId') }),
+        startedAt: new Date().toISOString(),
+      };
+      run.toolPartIds.set(event.toolCallId, part.partId);
+      run.callbackParts.push(part);
+      this.core.emitPartEvent(run, 'part.started', part);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  public onToolFinish(
+    state: IStorageState,
+    sessionId: string,
+    event: TFlexAgentToolCallFinishEvent,
+  ): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    if (!run.toolPartIds.has(event.toolCallId)) this.onToolStart(state, sessionId, event);
+    const partId = run.toolPartIds.get(event.toolCallId);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
+    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    try {
+      const trustedExecutionError = run.trustedToolExecutionErrors.get(event.toolCallId);
+      run.trustedToolExecutionErrors.delete(event.toolCallId);
+      const output = event.success ? normalizeJsonValue(event.output, this.core.toolOutputLimits) : undefined;
+      const projectedError = event.success
+        ? undefined
+        : this.core.projectExternalError(run, trustedExecutionError ?? event.error, 'toolCallback');
+      const bytes = event.success ? jsonBytes(output) : Buffer.byteLength(projectedError!.message);
+      if (!this.reserveCallbackCapacity(run, 1, bytes - (part.output === undefined ? 0 : jsonBytes(part.output)), 0)) return;
+      if (event.success) {
+        part.status = 'completed';
+        part.output = output!;
+      } else {
+        part.status = 'failed';
+        delete part.output;
+        part.error = projectedError!.message;
+      }
+      const original = run.deduplicatedToolCalls.get(event.toolCallId);
+      if (original !== undefined) {
+        part.deduplicatedFrom = this.core.boundedIdentifier(original, 'deduplicatedFrom');
+      }
+      part.completedAt = new Date().toISOString();
+      this.core.emitPartEvent(run, 'part.completed', part);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  public onToolUpdate(
+    state: IStorageState,
+    sessionId: string,
+    event: TFlexAgentToolCallUpdateEvent,
+  ): void {
+    let run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    if (!run.toolPartIds.has(event.toolCallId)) {
+      this.onToolStart(state, sessionId, event);
+      run = this.callbackRun(state, sessionId);
+      if (!run) return;
+    }
+    const partId = run.toolPartIds.get(event.toolCallId);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
+    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    try {
+      const output = normalizeJsonValue(event.output, this.core.toolOutputLimits);
+      if (!this.reserveCallbackCapacity(run, 1, jsonBytes(output) - (part.output === undefined ? 0 : jsonBytes(part.output)), 0)) return;
+      part.output = output;
+      this.core.emitPartEvent(run, 'part.updated', part);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  public 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.core.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.
+   */
+  public onModelCallUsage(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    event: plugins.TAgentModelCallUsageEvent,
+  ): void {
+    try {
+      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;
+      const operation = source === 'compaction' ? stored.metricsCompaction : run?.metricsOperation;
+      if (!operation) throw new Error('Model call usage has no owning metrics operation.');
+      observeSessionMetricsCall(operation, call);
+      let scopeId = run?.scopeId;
+      if (scopeId === undefined) {
+        const ambientContext = this.core.compaction.compactorInvocationContext.getStore();
+        const invocationContext = ambientContext
+          ? this.core.compaction.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.core.emitEvent(scopeId, stored.session, {
+        type: 'model.usage',
+        ...(generationId === undefined ? {} : { runId: generationId }),
+        source,
+        ...call,
+      });
+    } catch (error) {
+      // AgentSession isolates the entire callback, including event/context failures. Join it later.
+      stored.metricsFailure ??= error;
+      throw error;
+    }
+  }
+
+  public async settleMetricsOperation(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    operation: ISessionMetricsOperation,
+  ): Promise<void> {
+    try {
+      if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
+      await this.core.mutateProjection(state, stored, () => settleSessionMetricsOperation(stored.metrics, operation), true);
+    } catch (error) {
+      stored.metricsFailure ??= error;
+      // Never allow a later operation to overwrite a marker whose spend was not durably joined.
+      state.lifecycle = 'fenced';
+      throw error;
+    }
+  }
+
+  private callbackRun(state: IStorageState, sessionId: string): IActiveRun | undefined {
+    const run = state.activeRuns.get(sessionId);
+    return !run || run.callbacksClosed || run.callbackError ? undefined : run;
+  }
+
+  public reserveCallbackCapacity(
+    run: IActiveRun,
+    eventCount: number,
+    outputBytes: number,
+    partCount: number,
+  ): boolean {
+    const nextEvents = run.callbackEventCount + eventCount;
+    const nextOutputBytes = run.callbackOutputBytes + outputBytes;
+    const nextParts = run.callbackParts.length + partCount;
+    if (
+      !Number.isSafeInteger(nextEvents)
+      || !Number.isSafeInteger(nextOutputBytes)
+      || !Number.isSafeInteger(nextParts)
+      || nextEvents > this.core.callbackLimits.maxEvents
+      || nextOutputBytes > this.core.callbackLimits.maxOutputBytes
+      || nextParts > this.core.callbackLimits.maxParts
+    ) {
+      this.failCallback(run, this.core.trustInternalError(new FlexHarnessCallbackOverflowError(
+        `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
+      )));
+      return false;
+    }
+    run.callbackEventCount = nextEvents;
+    run.callbackOutputBytes = nextOutputBytes;
+    return true;
+  }
+
+  private failCallback(run: IActiveRun, error: Error): void {
+    run.callbackError ??= error;
+    this.core.runs.abortRunInternally(run, error);
+  }
+}