@modelprofile.com/flexharness-agent 6.0.0 → 7.0.0

package/ts_agent/smartagent.classes.session.ts

@@ -1,2588 +1,30 @@
-import * as plugins from './plugins.js';
-import { buildModelMessages } from './smartagent.context.js';
-import {
-  createAgentEvent,
-  createAgentEventId,
-  modelMessagesToAgentEvents,
-  type IArchivedAgentGenerationTransaction,
-  type IAssistantMessageEvent,
-  type IContextCompactionEvent,
-  type IGenerationBegunEvent,
-  type IGenerationExecutionCompletedEvent,
-  type IGenerationExecutionStartedEvent,
-  type IGenerationOutcomeEvent,
-  type IRuntimeEvent,
-  type IToolCallEvent,
-  type IToolExecutionIntentEvent,
-  type IToolExecutionReconciliationEvent,
-  type IToolResultEvent,
-  type IUserMessageEvent,
-  type TAgentEvent,
-  type TAgentGenerationOutcome,
-  type TAgentToolResultOutput,
-} from './smartagent.events.js';
-import {
-  AgentGenerationLeaseCleanupError,
-  ContextOverflowError,
-  type IAgentGenerateOptions,
-  type IAgentGenerateResult,
-  type IAgentGenerationHandle,
-  type IAgentGenerationLease,
-  type IAgentCompactOptions,
-  type IAgentBeginGenerationOptions,
-  type IAgentSession,
-  type IAgentSessionAbortOptions,
-  type IAgentSessionChange,
-  type IAgentSessionOptions,
-  type IAgentScheduleGenerateOptions,
-  type IAgentToolCallRecord,
-  type IAgentToolCallStartEvent,
-  type IAgentToolCallUpdateEvent,
-  type TAgentSessionChangeListener,
-  type TAgentCacheSetting,
-  type TAgentGenerationPrepare,
-  type TAgentPrompt,
-  type TAgentToolCallFinishEvent,
-  type TAgentToolExecutionReconciliationOptions,
-} from './smartagent.interfaces.js';
-import {
-  isAgentEventStoreV2,
-  validateAgentEventSnapshotV2,
-} from './smartagent.persistence.js';
-import type {
-  IAgentEventArchive,
-  IAgentEventArchiveV2,
-  TAgentEventArchive,
-  TAgentEventSnapshot,
-} from './smartagent.persistence.js';
-import {
-  filterModelVisibleAgentEvents,
-  getAgentGenerationTransactions,
-  getOpenAgentGenerationTransactions,
-  getUncertainToolExecutionIntents,
-  type IAgentGenerationTransaction,
-} from './smartagent.transactions.js';
-
-const RETRY_INITIAL_DELAY = 2000;
-const RETRY_BACKOFF_FACTOR = 2;
-const RETRY_MAX_DELAY = 30_000;
-const MAX_RETRY_ATTEMPTS = 8;
-
-const isTransactionalControlEvent = (event: TAgentEvent): boolean =>
-  event.type === 'generation-begun'
-  || event.type === 'generation-execution-started'
-  || event.type === 'generation-execution-completed'
-  || event.type === 'generation-outcome'
-  || event.type === 'tool-execution-intent'
-  || event.type === 'tool-execution-reconciliation';
-
-interface IToolCallPreparationLedgerEntry {
-  signature: string;
-  promise: Promise<void>;
-}
-
-interface IToolExecutionLedgerEntry {
-  signature: string;
-  promise: Promise<unknown>;
-}
-
-interface ICombinedAbortSignal {
-  signal: AbortSignal;
-  cleanup: () => void;
-}
-
-interface IScheduledGeneration {
-  state: 'debouncing' | 'queued';
-  debounceMs: number;
-  model?: plugins.TSmartAiLanguageModel;
-  system?: string;
-  tools?: plugins.ToolSet;
-  providerOptions?: plugins.ProviderOptions;
-  cache?: TAgentCacheSetting;
-  maxSteps?: number;
-  abort?: AbortSignal;
-  transaction?: IAgentGenerationHandle;
-  prepare?: TAgentGenerationPrepare;
-  timer: NodeJS.Timeout;
-  controller: AbortController;
-  removeAbortListener: () => void;
-  promise: Promise<IAgentGenerateResult>;
-  resolve: (result: IAgentGenerateResult) => void;
-  reject: (error: unknown) => void;
-}
-
-interface IEffectiveGenerationRuntime {
-  model: plugins.TSmartAiLanguageModel;
-  system?: string;
-  tools: plugins.ToolSet;
-  providerOptions?: plugins.ProviderOptions;
-  maxSteps: number;
-}
-
-interface IAgentSessionListenerState {
-  listener: TAgentSessionChangeListener;
-  queue: IAgentSessionChange[];
-  deliveryPromise?: Promise<void>;
-  executing: boolean;
-  subscribed: boolean;
-}
-
-interface IGenerationCallbackState {
-  active: boolean;
-}
-
-interface IGenerationLeaseCleanupOwnership {
-  lease: IAgentGenerationLease;
-  settled: boolean;
-}
-
-const sessionHydrations = new WeakMap<IAgentSessionOptions, TAgentEventSnapshot | undefined>();
-
-const retryDelay = (attempt: number, headers?: Record<string, string>): number => {
-  if (headers) {
-    const milliseconds = headers['retry-after-ms'];
-    if (milliseconds) {
-      const parsed = Number.parseFloat(milliseconds);
-      if (!Number.isNaN(parsed)) return parsed;
-    }
-    const retryAfter = headers['retry-after'];
-    if (retryAfter) {
-      const seconds = Number.parseFloat(retryAfter);
-      if (!Number.isNaN(seconds)) return Math.ceil(seconds * 1000);
-      const dateDelay = Date.parse(retryAfter) - Date.now();
-      if (!Number.isNaN(dateDelay) && dateDelay > 0) return Math.ceil(dateDelay);
-    }
-  }
-  return Math.min(
-    RETRY_INITIAL_DELAY * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1),
-    RETRY_MAX_DELAY,
-  );
-};
-
-const sleep = async (milliseconds: number, signal?: AbortSignal): Promise<void> =>
-  new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
-      return;
-    }
-    let settled = false;
-    const cleanup = () => signal?.removeEventListener('abort', onAbort);
-    const onAbort = () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      cleanup();
-      reject(signal?.reason ?? new DOMException('Aborted', 'AbortError'));
-    };
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      resolve();
-    }, milliseconds);
-    signal?.addEventListener('abort', onAbort, { once: true });
-  });
-
-const combineAbortSignals = (signals: Array<AbortSignal | undefined>): ICombinedAbortSignal => {
-  const controller = new AbortController();
-  const activeSignals = signals.filter((signal): signal is AbortSignal => !!signal);
-  const listeners = new Map<AbortSignal, () => void>();
-  const cleanup = () => {
-    for (const [signal, listener] of listeners) signal.removeEventListener('abort', listener);
-    listeners.clear();
-  };
-  for (const signal of activeSignals) {
-    const listener = () => {
-      if (!controller.signal.aborted) {
-        controller.abort(signal.reason ?? new DOMException('Aborted', 'AbortError'));
-      }
-      cleanup();
-    };
-    if (signal.aborted) {
-      listener();
-      break;
-    }
-    listeners.set(signal, listener);
-    signal.addEventListener('abort', listener, { once: true });
-  }
-  return { signal: controller.signal, cleanup };
-};
-
-const waitWithAbort = <TValue>(
-  promise: Promise<TValue>,
-  signals: Array<AbortSignal | undefined>,
-): Promise<TValue> => {
-  const activeSignals = signals.filter((signal): signal is AbortSignal => !!signal);
-  if (activeSignals.length === 0) return promise;
-  return new Promise<TValue>((resolve, reject) => {
-    let settled = false;
-    const listeners = new Map<AbortSignal, () => void>();
-    const cleanup = () => {
-      for (const [signal, listener] of listeners) signal.removeEventListener('abort', listener);
-      listeners.clear();
-    };
-    const settle = (handler: () => void) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      handler();
-    };
-    for (const signal of activeSignals) {
-      const listener = () => settle(() => reject(
-        signal.reason ?? new DOMException('Aborted', 'AbortError'),
-      ));
-      if (signal.aborted) {
-        listener();
-        return;
-      }
-      listeners.set(signal, listener);
-      signal.addEventListener('abort', listener, { once: true });
-    }
-    promise.then(
-      (value) => settle(() => resolve(value)),
-      (error) => settle(() => reject(error)),
-    );
-  });
-};
-
-const isRetryableError = (error: unknown): boolean => {
-  const candidate = error as { status?: number; statusCode?: number };
-  const status = candidate?.status ?? candidate?.statusCode;
-  if (status === 429 || status === 529 || status === 503) return true;
-  if (!(error instanceof Error)) return false;
-  const message = error.message.toLowerCase();
-  return message.includes('rate limit')
-    || message.includes('overloaded')
-    || message.includes('too many requests');
-};
-
-const isContextOverflow = (error: unknown): boolean => {
-  if (!(error instanceof Error)) return false;
-  const message = error.message.toLowerCase();
-  return message.includes('context_length_exceeded')
-    || message.includes('context window')
-    || message.includes('maximum context length')
-    || message.includes('too many tokens')
-    || message.includes('input is too long')
-    || error.name === 'AI_ContextWindowExceededError';
-};
-
-const parseToolInput = (input: unknown): unknown => {
-  if (typeof input !== 'string') return input;
-  try {
-    return JSON.parse(input);
-  } catch {
-    return input;
-  }
-};
-
-const errorToString = (error: unknown): string =>
-  error instanceof Error ? error.message : String(error);
-
-const toolSignature = (toolName: string, input: unknown): string => {
-  let serializedInput: string;
-  try {
-    serializedInput = JSON.stringify(input);
-  } catch {
-    serializedInput = String(input);
-  }
-  return `${toolName}\n${serializedInput}`;
-};
-
-const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
-  ((typeof value === 'object' && value !== null) || typeof value === 'function')
-  && typeof (value as { then?: unknown }).then === 'function';
-
-const isAsyncIterable = (value: unknown): value is AsyncIterable<unknown> =>
-  ((typeof value === 'object' && value !== null) || typeof value === 'function')
-  && typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function';
-
-const fallbackModelOutput = (output: unknown, error?: string): TAgentToolResultOutput => {
-  if (error !== undefined) return { type: 'error-text', value: error };
-  if (typeof output === 'string') return { type: 'text', value: output };
-  let jsonOutput: unknown;
-  try {
-    jsonOutput = output === undefined ? null : JSON.parse(JSON.stringify(output));
-  } catch {
-    jsonOutput = String(output);
-  }
-  return { type: 'json', value: jsonOutput } as TAgentToolResultOutput;
-};
-
-const recordToolCall = (
-  toolCalls: IAgentToolCallRecord[],
-  toolCallIndexes: Map<string, number>,
-  toolCall: { toolCallId?: unknown; toolName?: unknown; input?: unknown; args?: unknown },
-  update: { output?: unknown; error?: unknown } = {},
-): void => {
-  const toolCallId = String(toolCall.toolCallId ?? '');
-  const nextRecord: IAgentToolCallRecord = {
-    toolCallId,
-    toolName: String(toolCall.toolName ?? ''),
-    input: parseToolInput(toolCall.input ?? toolCall.args),
-  };
-  const hasOutput = Object.prototype.hasOwnProperty.call(update, 'output');
-  const hasError = Object.prototype.hasOwnProperty.call(update, 'error');
-  if (hasOutput) nextRecord.output = update.output;
-  if (hasError && update.error !== undefined) nextRecord.error = errorToString(update.error);
-
-  const existingIndex = toolCallIndexes.get(toolCallId);
-  if (existingIndex !== undefined) {
-    const existing = toolCalls[existingIndex];
-    existing.toolName = nextRecord.toolName || existing.toolName;
-    if (nextRecord.input !== undefined) existing.input = nextRecord.input;
-    if (hasOutput) existing.output = nextRecord.output;
-    if (nextRecord.error !== undefined) existing.error = nextRecord.error;
-    return;
-  }
-  toolCalls.push(nextRecord);
-  toolCallIndexes.set(toolCallId, toolCalls.length - 1);
-};
-
-export class AgentSession implements IAgentSession {
-  private readonly options: IAgentSessionOptions;
-  private readonly events: TAgentEvent[] = [];
-  private readonly eventIds = new Set<string>();
-  private readonly generationHandles = new Map<string, IAgentGenerationHandle>();
-  private readonly unresolvedLeaseCleanups = new Set<IGenerationLeaseCleanupOwnership>();
-  private sequence = 0;
-  private persistenceRevision = 0;
-  private persistenceQueue: Promise<void> = Promise.resolve();
-  private persistenceError: unknown;
-  private readonly notificationDispatches = new Set<Promise<void>>();
-  private readonly listeners = new Map<TAgentSessionChangeListener, IAgentSessionListenerState>();
-  private readonly scheduledGenerations = new Map<string, IScheduledGeneration>();
-  private readonly generationCallbackContext = new plugins.AsyncLocalStorage<IGenerationCallbackState>();
-  private retentionPromise: Promise<void> | undefined;
-  private maintenanceError: unknown;
-  private generationQueue: Promise<void> = Promise.resolve();
-  private currentGenerationAbortController: AbortController | undefined;
-  private readonly sessionAbortController = new AbortController();
-  private jobUnsubscribe: (() => void) | undefined;
-  private closed = false;
-  private closeFinalizationReached = false;
-  private closeCleanupCompletedState = false;
-
-  public get closeCleanupCompleted(): boolean {
-    return this.closeCleanupCompletedState;
-  }
-
-  private refreshCloseCleanupCompleted(): void {
-    this.closeCleanupCompletedState = this.closeFinalizationReached
-      && this.jobUnsubscribe === undefined
-      && this.unresolvedLeaseCleanups.size === 0;
-  }
-
-  public static async create(options: IAgentSessionOptions): Promise<AgentSession> {
-    if (!options.eventStore) return new AgentSession(options);
-    if (!options.sessionId?.trim()) {
-      throw new Error('AgentSession.create() requires sessionId when eventStore is configured.');
-    }
-    let snapshot = await options.eventStore.load(options.sessionId);
-    const v2Store = isAgentEventStoreV2(options.eventStore);
-    if (
-      snapshot
-      && ((!v2Store && snapshot.schemaVersion !== 1)
-        || (v2Store && snapshot.schemaVersion !== 1 && snapshot.schemaVersion !== 2))
-    ) {
-      throw new Error(
-        `Unsupported agent event snapshot schema version ${String((snapshot as { schemaVersion?: unknown }).schemaVersion)}.`,
-      );
-    }
-    if (!v2Store && snapshot?.events.some(isTransactionalControlEvent)) {
-      throw new Error('Transactional events require an IAgentEventStoreV2-capable event store.');
-    }
-    if (snapshot?.schemaVersion === 2) {
-      snapshot = validateAgentEventSnapshotV2(snapshot, options.sessionId);
-    }
-    sessionHydrations.set(options, snapshot);
-    let session: AgentSession;
-    try {
-      session = new AgentSession(options);
-    } finally {
-      sessionHydrations.delete(options);
-    }
-    await session.interruptRestoredTransactions();
-    await session.flushPersistence();
-    await session.runEventRetentionLocked();
-    session.attachJobSubscription();
-    return session;
-  }
-
+import * as plugins from './plugins.node.js';
+import { AgentSessionEngine } from './classes.sessionengine.js';
+import type { IAgentSessionOptions } from './smartagent.interfaces.js';
+import type { IAgentCallbackState, IAgentRuntimePlatform } from './runtime.interfaces.js';
+
+const nodePlatform: IAgentRuntimePlatform = {
+  createClaimToken: () => plugins.crypto.randomBytes(32).toString('base64url'),
+  hashClaimToken: (token) => plugins.crypto.createHash('sha256').update(token).digest('hex'),
+  equalClaimDigests: (left, right) => plugins.crypto.timingSafeEqual(
+    Buffer.from(left, 'hex'), Buffer.from(right, 'hex'),
+  ),
+  isDeepEqual: plugins.isDeepStrictEqual,
+  reportListenerError: (error) => process.emitWarning(error instanceof Error ? error : String(error), {
+    code: 'SMARTAGENT_SESSION_LISTENER_ERROR',
+  }),
+};
+
+/** Node session facade; callback ancestry remains isolated with AsyncLocalStorage. */
+export class AgentSession extends AgentSessionEngine {
   constructor(options: IAgentSessionOptions) {
-    this.options = options;
-    const hasHydration = sessionHydrations.has(options);
-    const hydrationSnapshot = sessionHydrations.get(options);
-    if (options.eventStore && !hasHydration) {
-      throw new Error('Use AgentSession.create() when eventStore is configured.');
-    }
-    if (options.eventStore && !options.sessionId?.trim()) {
-      throw new Error('sessionId is required when eventStore is configured.');
-    }
-    const tools = options.tools ?? {};
-    if (Object.prototype.hasOwnProperty.call(tools, 'invalid')) {
-      throw new Error('Tool name "invalid" is reserved for SmartAgent tool-call repair.');
-    }
-    const maxContextOverflowRetries = options.maxContextOverflowRetries ?? 3;
-    if (!Number.isSafeInteger(maxContextOverflowRetries) || maxContextOverflowRetries < 0) {
-      throw new Error('maxContextOverflowRetries must be a non-negative integer.');
-    }
-    const changeListenerTimeoutMs = options.changeListenerTimeoutMs ?? 30_000;
-    if (!Number.isSafeInteger(changeListenerTimeoutMs) || changeListenerTimeoutMs <= 0) {
-      throw new Error('changeListenerTimeoutMs must be a positive integer.');
-    }
-    const maxPendingSessionChanges = options.maxPendingSessionChanges ?? 1000;
-    if (!Number.isSafeInteger(maxPendingSessionChanges) || maxPendingSessionChanges <= 0) {
-      throw new Error('maxPendingSessionChanges must be a positive integer.');
-    }
-    const generationLeaseCleanupTimeoutMs = options.generationLeaseCleanupTimeoutMs ?? 30_000;
-    if (!Number.isSafeInteger(generationLeaseCleanupTimeoutMs) || generationLeaseCleanupTimeoutMs <= 0) {
-      throw new Error('generationLeaseCleanupTimeoutMs must be a positive integer.');
-    }
-    const maxArchivedTransactionTombstones = options.maxArchivedTransactionTombstones ?? 1000;
-    if (
-      !Number.isSafeInteger(maxArchivedTransactionTombstones)
-      || maxArchivedTransactionTombstones <= 0
-    ) {
-      throw new Error('maxArchivedTransactionTombstones must be a positive integer.');
-    }
-    if (options.eventRetention) {
-      if (
-        !Number.isSafeInteger(options.eventRetention.maxEvents)
-        || options.eventRetention.maxEvents <= 0
-      ) {
-        throw new Error('eventRetention.maxEvents must be a positive integer.');
-      }
-      if (!options.contextCompactor) {
-        throw new Error('eventRetention requires contextCompactor.');
-      }
-      if (!options.eventStore?.archive) {
-        throw new Error('eventRetention requires an eventStore with archive support.');
-      }
-    }
-
-    if (hydrationSnapshot) {
-      this.persistenceRevision = hydrationSnapshot.revision;
-      for (const event of hydrationSnapshot.events) this.restoreEvent(event);
-    }
-    const initialEvents: TAgentEvent[] = [
-      ...(options.events ?? []),
-      ...modelMessagesToAgentEvents(options.messages ?? []),
-    ];
-    if (hydrationSnapshot && initialEvents.length > 0) {
-      throw new Error('Persisted sessions cannot also receive initial events or messages.');
-    }
-    if (
-      options.eventStore
-      && !isAgentEventStoreV2(options.eventStore)
-      && initialEvents.some(isTransactionalControlEvent)
-    ) {
-      throw new Error('Transactional events require an IAgentEventStoreV2-capable event store.');
-    }
-    for (const event of initialEvents) this.commitEvent(event, false);
-    if (options.eventStore && (!hydrationSnapshot || initialEvents.length > 0)) {
-      this.queuePersistence();
-    }
-    if (!options.eventStore) this.attachJobSubscription();
-  }
-
-  private attachJobSubscription(): void {
-    if (this.jobUnsubscribe) return;
-    this.jobUnsubscribe = this.options.executionContext?.jobs?.subscribe?.(async (jobEvent) => {
-      if (this.closed) return;
-      const job = jobEvent.job;
-      const runtimeType = `${job.type}-${jobEvent.type}`;
-      await this.pushRuntimeEvent({
-        type: runtimeType,
-        executionId: job.executionId,
-        jobType: job.type,
-        state: job.state,
-        request: job.request,
-        exitCode: job.exitCode,
-        stdout: job.stdout,
-        stderr: job.stderr,
-        signal: job.signal,
-        ...(jobEvent.type === 'output'
-          ? {
-              stream: jobEvent.stream!,
-              chunk: jobEvent.chunk!,
-              outputSequence: jobEvent.sequence!,
-            }
-          : {}),
-      });
-    });
-  }
-
-  private restoreEvent(event: TAgentEvent): void {
-    if (this.eventIds.has(event.id)) throw new Error(`Duplicate agent event id "${event.id}".`);
-    if (!Number.isSafeInteger(event.sequence) || (event.sequence ?? 0) <= this.sequence) {
-      throw new Error(`Invalid persisted sequence for agent event "${event.id}".`);
-    }
-    this.events.push(event);
-    this.eventIds.add(event.id);
-    this.sequence = event.sequence!;
-  }
-
-  private queuePersistence(): Promise<void> {
-    if (!this.options.eventStore) return Promise.resolve();
-    const snapshot = structuredClone(this.events);
-    const operation = this.persistenceQueue.then(async () => {
-      if (this.persistenceError !== undefined) throw this.persistenceError;
-      this.persistenceRevision = await this.options.eventStore!.save(
-        this.options.sessionId!,
-        snapshot,
-        this.persistenceRevision,
-      );
-    });
-    this.persistenceQueue = operation.catch((error) => {
-      this.persistenceError ??= error;
-    });
-    return operation;
-  }
-
-  private async flushPersistence(): Promise<void> {
-    await this.persistenceQueue;
-    if (this.persistenceError !== undefined) throw this.persistenceError;
-  }
-
-  private reportListenerError(error: unknown): void {
-    process.emitWarning(error instanceof Error ? error : String(error), {
-      code: 'SMARTAGENT_SESSION_LISTENER_ERROR',
-    });
-  }
-
-  private queueNotification(change: IAgentSessionChange, durability: Promise<void>): void {
-    const dispatch = (async () => {
-      try {
-        await durability;
-      } catch {
-        return;
-      }
-      for (const state of this.listeners.values()) {
-        this.enqueueListenerChange(state, change);
-      }
-    })();
-    this.notificationDispatches.add(dispatch);
-    void dispatch.then(
-      () => this.notificationDispatches.delete(dispatch),
-      () => this.notificationDispatches.delete(dispatch),
-    );
-  }
-
-  private enqueueListenerChange(
-    state: IAgentSessionListenerState,
-    change: IAgentSessionChange,
-  ): void {
-    if (!state.subscribed) return;
-    const maxPending = this.options.maxPendingSessionChanges ?? 1000;
-    if (state.queue.length >= maxPending) {
-      state.subscribed = false;
-      state.queue.length = 0;
-      this.listeners.delete(state.listener);
-      this.reportListenerError(new Error(
-        `Session change listener exceeded ${maxPending} pending changes and was removed.`,
-      ));
-      return;
-    }
-    state.queue.push(change);
-    if (state.deliveryPromise) return;
-    const delivery = this.deliverListenerChanges(state);
-    state.deliveryPromise = delivery;
-    void delivery.then(() => {
-      if (state.deliveryPromise === delivery) state.deliveryPromise = undefined;
+    super(options, nodePlatform, {
+      kind: 'exposed',
+      callbackScope: new plugins.AsyncLocalStorage<IAgentCallbackState>(),
     });
   }
 
-  private async deliverListenerChanges(state: IAgentSessionListenerState): Promise<void> {
-    while (state.subscribed && state.queue.length > 0) {
-      const change = state.queue.shift()!;
-      let timer: NodeJS.Timeout | undefined;
-      state.executing = true;
-      try {
-        await Promise.race([
-          Promise.resolve().then(() => state.listener(change)),
-          new Promise<never>((_resolve, reject) => {
-            timer = setTimeout(
-              () => reject(new Error(
-                `Session change listener timed out after ${this.options.changeListenerTimeoutMs ?? 30_000}ms.`,
-              )),
-              this.options.changeListenerTimeoutMs ?? 30_000,
-            );
-          }),
-        ]);
-      } catch (error) {
-        state.subscribed = false;
-        state.queue.length = 0;
-        this.listeners.delete(state.listener);
-        this.reportListenerError(error);
-      } finally {
-        state.executing = false;
-        if (timer) clearTimeout(timer);
-      }
-    }
-  }
-
-  private commitEvents<TEvent extends TAgentEvent>(
-    events: readonly TEvent[],
-    notify = true,
-  ): TEvent[] {
-    const nextIds = new Set<string>();
-    for (const event of events) {
-      if (this.eventIds.has(event.id) || nextIds.has(event.id)) {
-        throw new Error(`Duplicate agent event id "${event.id}".`);
-      }
-      nextIds.add(event.id);
-    }
-    if (this.options.eventStore) structuredClone(events);
-    const committedEvents = events.map((event) => ({
-      ...event,
-      sequence: ++this.sequence,
-    }) as TEvent);
-    for (const event of committedEvents) {
-      this.events.push(event);
-      this.eventIds.add(event.id);
-      if (event.type === 'generation-outcome') {
-        this.generationHandles.delete(event.generationId);
-      }
-    }
-    if (notify && committedEvents.length > 0) {
-      const durability = this.queuePersistence();
-      this.queueNotification({ type: 'committed', events: committedEvents }, durability);
-    }
-    return committedEvents;
-  }
-
-  private commitEvent<TEvent extends TAgentEvent>(event: TEvent, notify = true): TEvent {
-    return this.commitEvents([event], notify)[0];
-  }
-
-  public pushEvent(event: TAgentEvent): Promise<void> {
-    if (this.closed) return Promise.reject(new Error('AgentSession is closed.'));
-    if (this.persistenceError !== undefined) return Promise.reject(this.persistenceError);
-    if (this.maintenanceError !== undefined) return Promise.reject(this.maintenanceError);
-    if (
-      isTransactionalControlEvent(event)
-      && this.options.eventStore
-      && !isAgentEventStoreV2(this.options.eventStore)
-    ) {
-      return Promise.reject(
-        new Error('Transactional events require an IAgentEventStoreV2-capable event store.'),
-      );
-    }
-    this.commitEvent(event);
-    return this.flushPersistence().then(async () => {
-      this.scheduleEventRetention();
-      if (!this.currentGenerationAbortController && this.retentionPromise) {
-        await this.retentionPromise;
-      }
-    });
-  }
-
-  public pushUserMessage(content: TAgentPrompt): Promise<void> {
-    return this.pushEvent(createAgentEvent<IUserMessageEvent>({
-      type: 'user-message',
-      content,
-      parentIds: this.events.length > 0 ? [this.events[this.events.length - 1].id] : undefined,
-    }));
-  }
-
-  public pushRuntimeEvent(event: import('./smartagent.events.js').IAgentRuntimeEventPayload): Promise<void> {
-    return this.pushEvent(createAgentEvent<IRuntimeEvent>({
-      type: 'runtime-event',
-      event,
-      parentIds: this.events.length > 0 ? [this.events[this.events.length - 1].id] : undefined,
-    }));
-  }
-
-  private transaction(generationId: string): IAgentGenerationTransaction {
-    const transaction = getAgentGenerationTransactions(this.events).get(generationId);
-    if (!transaction) {
-      throw new Error(`Unknown transactional generation "${generationId}".`);
-    }
-    if (transaction.state === 'invalid') {
-      throw new Error(`Transactional generation "${generationId}" has an invalid event sequence.`);
-    }
-    return transaction;
-  }
-
-  private archivedTransaction(
-    generationId: string,
-  ): IArchivedAgentGenerationTransaction | undefined {
-    for (let index = this.events.length - 1; index >= 0; index--) {
-      const event = this.events[index];
-      if (event.type !== 'context-compaction') continue;
-      const transaction = event.archivedTransactions?.find((entry) =>
-        entry.generationId === generationId);
-      if (transaction) return transaction;
-    }
-    return undefined;
-  }
-
-  private verifyGenerationClaim(
-    transaction: IAgentGenerationHandle,
-  ): IAgentGenerationTransaction | IArchivedAgentGenerationTransaction {
-    if (!transaction?.generationId?.trim() || !transaction.claimToken?.trim()) {
-      throw new Error('A valid transactional generation handle is required.');
-    }
-    const activeTransaction = getAgentGenerationTransactions(this.events).get(transaction.generationId);
-    if (activeTransaction?.state === 'invalid') {
-      throw new Error(
-        `Transactional generation "${transaction.generationId}" has an invalid event sequence.`,
-      );
-    }
-    const state = activeTransaction ?? this.archivedTransaction(transaction.generationId);
-    if (!state) throw new Error(`Unknown transactional generation "${transaction.generationId}".`);
-    const expectedDigest = 'begun' in state
-      ? state.begun.claimTokenDigest
-      : state.claimTokenDigest;
-    const actualDigest = plugins.crypto
-      .createHash('sha256')
-      .update(transaction.claimToken)
-      .digest('hex');
-    if (
-      !/^[a-f0-9]{64}$/.test(expectedDigest)
-      || !plugins.crypto.timingSafeEqual(
-        Buffer.from(expectedDigest, 'hex'),
-        Buffer.from(actualDigest, 'hex'),
-      )
-    ) {
-      throw new Error(`Invalid claim for transactional generation "${transaction.generationId}".`);
-    }
-    return state;
-  }
-
-  private async interruptRestoredTransactions(): Promise<void> {
-    const openTransactions = getOpenAgentGenerationTransactions(this.events);
-    if (openTransactions.length === 0) return;
-    if (openTransactions.some((transaction) => transaction.state === 'invalid')) {
-      throw new Error('Cannot restore a session with an invalid transactional generation sequence.');
-    }
-    this.commitEvents(openTransactions.map((transaction) =>
-      createAgentEvent<IGenerationOutcomeEvent>({
-        type: 'generation-outcome',
-        generationId: transaction.generationId,
-        outcome: 'interrupted',
-        reason: 'Session restoration interrupted nonterminal transactional execution.',
-        parentIds: [
-          transaction.executionCompleted?.id
-          ?? transaction.executionStarted?.id
-          ?? transaction.begun.id,
-        ],
-      })));
-    await this.flushPersistence();
-  }
-
-  private transactionalStoreCapabilityError(): Error | undefined {
-    return this.options.eventStore && !isAgentEventStoreV2(this.options.eventStore)
-      ? new Error('Transactional generations require an IAgentEventStoreV2-capable event store.')
-      : undefined;
-  }
-
-  public beginGeneration(
-    content: TAgentPrompt,
-    options: IAgentBeginGenerationOptions = {},
-  ): Promise<IAgentGenerationHandle> {
-    const capabilityError = this.transactionalStoreCapabilityError();
-    if (capabilityError) return Promise.reject(capabilityError);
-    return this.queueExclusive(async () => {
-      await this.flushPersistence();
-      const generationId = options.generationId ?? createAgentEventId('generation');
-      if (!generationId.trim()) throw new Error('Transactional generationId must not be empty.');
-      const existingTransaction = getAgentGenerationTransactions(this.events).get(generationId);
-      if (existingTransaction) {
-        if (existingTransaction.state === 'invalid') {
-          throw new Error(`Transactional generation "${generationId}" has an invalid event sequence.`);
-        }
-        const existingMessage = this.events.find((event): event is IUserMessageEvent =>
-          event.type === 'user-message'
-          && event.generationId === generationId
-          && event.causationId === existingTransaction.begun.id);
-        const handle = this.generationHandles.get(generationId);
-        if (handle && existingMessage && plugins.isDeepStrictEqual(existingMessage.content, content)) {
-          return handle;
-        }
-        throw new Error(
-          `Transactional generation "${generationId}" already exists and its claim cannot be reissued.`,
-        );
-      }
-      if (this.events.some((event) => event.generationId === generationId)) {
-        throw new Error(`Generation id "${generationId}" is already correlated with legacy events.`);
-      }
-      if (this.archivedTransaction(generationId) || this.generationHandles.has(generationId)) {
-        throw new Error(
-          `Transactional generation "${generationId}" already exists and its claim cannot be reissued.`,
-        );
-      }
-      const claimToken = plugins.crypto.randomBytes(32).toString('base64url');
-      const claimTokenDigest = plugins.crypto
-        .createHash('sha256')
-        .update(claimToken)
-        .digest('hex');
-      const priorEvent = this.events[this.events.length - 1];
-      const begun = createAgentEvent<IGenerationBegunEvent>({
-        type: 'generation-begun',
-        generationId,
-        claimTokenDigest,
-        parentIds: priorEvent ? [priorEvent.id] : undefined,
-      });
-      const userMessage = createAgentEvent<IUserMessageEvent>({
-        type: 'user-message',
-        content,
-        generationId,
-        causationId: begun.id,
-        parentIds: [begun.id],
-      });
-      this.commitEvents([begun, userMessage]);
-      const handle = Object.freeze({ generationId, claimToken });
-      this.generationHandles.set(generationId, handle);
-      await this.flushPersistence();
-      this.scheduleEventRetention();
-      return handle;
-    });
-  }
-
-  private async appendGenerationOutcome(
-    generationId: string,
-    outcome: TAgentGenerationOutcome,
-    reason?: string,
-  ): Promise<void> {
-    const transaction = this.transaction(generationId);
-    if (
-      transaction.state === 'accepted'
-      || transaction.state === 'rejected'
-      || transaction.state === 'interrupted'
-    ) {
-      if (transaction.state === outcome) return;
-      throw new Error(
-        `Transactional generation "${generationId}" already has outcome "${transaction.state}".`,
-      );
-    }
-    if (outcome !== 'interrupted') {
-      if (transaction.state !== 'execution-completed') {
-        throw new Error(
-          `Transactional generation "${generationId}" must be execution-completed before ${outcome}.`,
-        );
-      }
-      if (getUncertainToolExecutionIntents(this.events, generationId).length > 0) {
-        throw new Error(
-          `Transactional generation "${generationId}" has unresolved tool execution intents.`,
-        );
-      }
-    }
-    const parent = transaction.executionCompleted
-      ?? transaction.executionStarted
-      ?? transaction.begun;
-    this.commitEvent(createAgentEvent<IGenerationOutcomeEvent>({
-      type: 'generation-outcome',
-      generationId,
-      outcome,
-      reason,
-      parentIds: [parent.id],
-    }));
-    await this.flushPersistence();
-    this.scheduleEventRetention();
-  }
-
-  private transactionOutcomeErrorReason(error: unknown): string {
-    if (this.options.transactionOutcomeErrorProjector) {
-      try {
-        const projected = this.options.transactionOutcomeErrorProjector(error);
-        if (typeof projected === 'string' && projected.trim()) return projected;
-      } catch {
-        // Invalid projectors fall back to the normal diagnostic reason.
-      }
-    }
-    return errorToString(error);
-  }
-
-  public finalizeGeneration(
-    transaction: IAgentGenerationHandle,
-    outcome: TAgentGenerationOutcome,
-  ): Promise<void> {
-    const capabilityError = this.transactionalStoreCapabilityError();
-    if (capabilityError) return Promise.reject(capabilityError);
-    return this.queueExclusive(async () => {
-      if (!['accepted', 'rejected', 'interrupted'].includes(outcome)) {
-        throw new Error(`Invalid transactional generation outcome "${String(outcome)}".`);
-      }
-      const state = this.verifyGenerationClaim(transaction);
-      if (!('begun' in state)) {
-        if (state.outcome === outcome) return;
-        throw new Error(
-          `Transactional generation "${transaction.generationId}" already has outcome "${state.outcome}".`,
-        );
-      }
-      await this.appendGenerationOutcome(transaction.generationId, outcome);
-    });
-  }
-
-  public listUncertainToolExecutions(): IToolExecutionIntentEvent[] {
-    return structuredClone(getUncertainToolExecutionIntents(this.events));
-  }
-
-  public reconcileToolExecution(
-    intentId: string,
-    reconciliation: TAgentToolExecutionReconciliationOptions,
-  ): Promise<void> {
-    const capabilityError = this.transactionalStoreCapabilityError();
-    if (capabilityError) return Promise.reject(capabilityError);
-    return this.queueExclusive(async () => {
-      await this.flushPersistence();
-      const intent = this.events.find((event): event is IToolExecutionIntentEvent =>
-        event.type === 'tool-execution-intent' && event.id === intentId);
-      if (!intent) throw new Error(`Unknown tool execution intent "${intentId}".`);
-      const defaultError = reconciliation.resolution === 'not-executed'
-        ? 'Tool execution was reconciled as not executed.'
-        : reconciliation.resolution === 'abandoned-unknown'
-          ? 'Tool execution was abandoned with an unknown outcome.'
-          : undefined;
-      const error = reconciliation.resolution === 'executed'
-        ? undefined
-        : reconciliation.error ?? defaultError;
-      const existing = this.events.find((event): event is IToolExecutionReconciliationEvent =>
-        event.type === 'tool-execution-reconciliation' && event.intentId === intentId);
-      if (existing) {
-        const same = existing.resolution === reconciliation.resolution
-          && existing.error === error
-          && plugins.isDeepStrictEqual(
-            existing.output,
-            reconciliation.resolution === 'executed' ? reconciliation.output : undefined,
-          )
-          && plugins.isDeepStrictEqual(
-            existing.modelOutput,
-            reconciliation.resolution === 'executed' ? reconciliation.modelOutput : undefined,
-          );
-        if (!same) throw new Error(`Tool execution intent "${intentId}" has a conflicting reconciliation.`);
-        return;
-      }
-      if (!getUncertainToolExecutionIntents(this.events).some((entry) => entry.id === intentId)) {
-        throw new Error(`Tool execution intent "${intentId}" already has a terminal result.`);
-      }
-      if (
-        reconciliation.resolution === 'executed'
-        && (!Object.prototype.hasOwnProperty.call(reconciliation, 'output') || !reconciliation.modelOutput)
-      ) {
-        throw new Error('Executed tool reconciliation requires explicit output and modelOutput.');
-      }
-      const toolCall = [...this.events].reverse().find((event): event is IToolCallEvent =>
-        event.type === 'tool-call'
-        && event.generationId === intent.generationId
-        && event.toolCallId === intent.toolCallId);
-      const reconciliationEvent = createAgentEvent<IToolExecutionReconciliationEvent>({
-        type: 'tool-execution-reconciliation',
-        generationId: intent.generationId,
-        inferenceId: intent.inferenceId,
-        causationId: intent.id,
-        intentId: intent.id,
-        toolCallId: intent.toolCallId,
-        toolName: intent.toolName,
-        resolution: reconciliation.resolution,
-        output: reconciliation.resolution === 'executed' ? reconciliation.output : undefined,
-        modelOutput: reconciliation.resolution === 'executed' ? reconciliation.modelOutput : undefined,
-        error,
-        parentIds: [intent.id],
-      });
-      const resultEvent = createAgentEvent<IToolResultEvent>({
-        type: 'tool-result',
-        generationId: intent.generationId,
-        inferenceId: intent.inferenceId,
-        causationId: intent.inferenceId,
-        executionIntentId: intent.id,
-        toolCallId: intent.toolCallId,
-        toolName: intent.toolName,
-        output: reconciliation.resolution === 'executed' ? reconciliation.output : undefined,
-        error,
-        modelOutput: reconciliation.resolution === 'executed'
-          ? reconciliation.modelOutput
-          : { type: 'error-text', value: error! },
-        parentIds: toolCall ? [toolCall.id] : [intent.id],
-      });
-      this.commitEvents([reconciliationEvent, resultEvent]);
-      await this.flushPersistence();
-      this.scheduleEventRetention();
-    });
-  }
-
-  public getEvents(): readonly TAgentEvent[] {
-    return this.events.slice();
-  }
-
-  public getModelMessages(): plugins.ModelMessage[] {
-    return this.buildContext(this.events);
-  }
-
-  private buildContext(events: readonly TAgentEvent[]): plugins.ModelMessage[] {
-    const visibleEvents = filterModelVisibleAgentEvents(events);
-    return this.options.contextBuilder
-      ? this.options.contextBuilder({ events: visibleEvents })
-      : buildModelMessages(visibleEvents);
-  }
-
-  public subscribe(listener: TAgentSessionChangeListener): () => void {
-    if (this.closed) throw new Error('AgentSession is closed.');
-    const existing = this.listeners.get(listener);
-    if (existing) {
-      return () => {
-        existing.subscribed = false;
-        existing.queue.length = 0;
-        this.listeners.delete(listener);
-      };
-    }
-    const state: IAgentSessionListenerState = {
-      listener,
-      queue: [],
-      executing: false,
-      subscribed: true,
-    };
-    this.listeners.set(listener, state);
-    return () => {
-      state.subscribed = false;
-      state.queue.length = 0;
-      this.listeners.delete(listener);
-    };
-  }
-
-  public scheduleGenerate(options: IAgentScheduleGenerateOptions): Promise<IAgentGenerateResult> {
-    if (this.closed) return Promise.reject(new Error('AgentSession is closed.'));
-    const capabilityError = options.transaction
-      ? this.transactionalStoreCapabilityError()
-      : undefined;
-    if (capabilityError) return Promise.reject(capabilityError);
-    if (!options.key.trim()) return Promise.reject(new Error('Scheduled generation key must not be empty.'));
-    const debounceMs = options.debounceMs ?? 50;
-    if (!Number.isSafeInteger(debounceMs) || debounceMs < 0) {
-      return Promise.reject(new Error('debounceMs must be a non-negative integer.'));
-    }
-    const existing = this.scheduledGenerations.get(options.key);
-    if (existing) {
-      if (
-        existing.model !== options.model
-        || existing.system !== options.system
-        || existing.tools !== options.tools
-        || existing.providerOptions !== options.providerOptions
-        || existing.cache !== options.cache
-        || existing.maxSteps !== options.maxSteps
-        || existing.abort !== options.abort
-        || existing.prepare !== options.prepare
-        || existing.transaction?.generationId !== options.transaction?.generationId
-        || existing.transaction?.claimToken !== options.transaction?.claimToken
-      ) {
-        return Promise.reject(new Error(`Conflicting options for scheduled generation "${options.key}".`));
-      }
-      if (existing.state === 'debouncing') {
-        clearTimeout(existing.timer);
-        existing.debounceMs = debounceMs;
-        existing.timer = setTimeout(() => this.startScheduledGeneration(options.key), debounceMs);
-      }
-      return existing.promise;
-    }
-
-    if (options.abort?.aborted) {
-      const abortReason = options.abort.reason ?? new DOMException('Aborted', 'AbortError');
-      if (!options.transaction) return Promise.reject(abortReason);
-      return this.queueExclusive(async () => {
-        const transaction = this.verifyGenerationClaim(options.transaction!);
-        if (!('begun' in transaction)) {
-          if (transaction.outcome === 'interrupted') throw abortReason;
-          throw new Error(
-            `Transactional generation "${transaction.generationId}" already has outcome "${transaction.outcome}".`,
-          );
-        }
-        await this.appendGenerationOutcome(
-          options.transaction!.generationId,
-          'interrupted',
-          this.transactionOutcomeErrorReason(abortReason),
-        );
-        throw abortReason;
-      });
-    }
-
-    let resolve!: (result: IAgentGenerateResult) => void;
-    let reject!: (error: unknown) => void;
-    const promise = new Promise<IAgentGenerateResult>((resolvePromise, rejectPromise) => {
-      resolve = resolvePromise;
-      reject = rejectPromise;
-    });
-    const controller = new AbortController();
-    const onAbort = () => this.cancelScheduledGeneration(
-      options.key,
-      options.abort?.reason ?? new DOMException('Aborted', 'AbortError'),
-    );
-    options.abort?.addEventListener('abort', onAbort, { once: true });
-    const scheduled: IScheduledGeneration = {
-      state: 'debouncing',
-      debounceMs,
-      model: options.model,
-      system: options.system,
-      tools: options.tools,
-      providerOptions: options.providerOptions,
-      cache: options.cache,
-      maxSteps: options.maxSteps,
-      abort: options.abort,
-      transaction: options.transaction,
-      prepare: options.prepare,
-      timer: setTimeout(() => this.startScheduledGeneration(options.key), debounceMs),
-      controller,
-      removeAbortListener: () => options.abort?.removeEventListener('abort', onAbort),
-      promise,
-      resolve,
-      reject,
-    };
-    this.scheduledGenerations.set(options.key, scheduled);
-    return promise;
-  }
-
-  private startScheduledGeneration(key: string): void {
-    const scheduled = this.scheduledGenerations.get(key);
-    if (!scheduled || scheduled.state !== 'debouncing') return;
-    scheduled.state = 'queued';
-    void this.generate({
-      model: scheduled.model,
-      system: scheduled.system,
-      tools: scheduled.tools,
-      providerOptions: scheduled.providerOptions,
-      cache: scheduled.cache,
-      maxSteps: scheduled.maxSteps,
-      abort: scheduled.controller.signal,
-      transaction: scheduled.transaction,
-      prepare: scheduled.prepare,
-    }).then(
-      (result) => this.settleScheduledGeneration(key, scheduled, () => scheduled.resolve(result)),
-      (error) => this.settleScheduledGeneration(key, scheduled, () => scheduled.reject(error)),
-    );
-  }
-
-  private settleScheduledGeneration(
-    key: string,
-    scheduled: IScheduledGeneration,
-    settle: () => void,
-  ): void {
-    if (this.scheduledGenerations.get(key) === scheduled) {
-      this.scheduledGenerations.delete(key);
-    }
-    scheduled.removeAbortListener();
-    settle();
-  }
-
-  public cancelScheduledGeneration(key: string, reason?: unknown): boolean {
-    const scheduled = this.scheduledGenerations.get(key);
-    if (!scheduled) return false;
-    clearTimeout(scheduled.timer);
-    this.scheduledGenerations.delete(key);
-    scheduled.removeAbortListener();
-    const cancellationReason = reason
-      ?? new DOMException('Scheduled generation cancelled', 'AbortError');
-    if (!scheduled.controller.signal.aborted) scheduled.controller.abort(cancellationReason);
-    if (!scheduled.transaction) {
-      scheduled.reject(cancellationReason);
-      return true;
-    }
-    let transaction: IAgentGenerationTransaction;
-    try {
-      const claim = this.verifyGenerationClaim(scheduled.transaction);
-      if (!('begun' in claim)) {
-        scheduled.reject(new Error(
-          `Transactional generation "${claim.generationId}" already has outcome "${claim.outcome}".`,
-        ));
-        return true;
-      }
-      transaction = claim;
-    } catch (error) {
-      scheduled.reject(error);
-      return true;
-    }
-    if (transaction.state === 'execution-started') return true;
-    void this.appendGenerationOutcome(
-      scheduled.transaction.generationId,
-      'interrupted',
-      this.transactionOutcomeErrorReason(cancellationReason),
-    ).then(
-      () => scheduled.reject(cancellationReason),
-      (error) => scheduled.reject(error),
-    );
-    return true;
-  }
-
-  private async performCompaction(
-    reason: 'context-overflow' | 'retention' | 'manual',
-    abortSignal?: AbortSignal,
-  ): Promise<IContextCompactionEvent | undefined> {
-    abortSignal?.throwIfAborted();
-    await this.flushPersistence();
-    abortSignal?.throwIfAborted();
-    const unresolvedIntents = getUncertainToolExecutionIntents(this.events);
-    if (unresolvedIntents.length > 0) {
-      if (reason === 'context-overflow' || reason === 'retention') return undefined;
-      throw new Error('Context compaction is blocked by unresolved tool execution intents.');
-    }
-    const openTransactions = getOpenAgentGenerationTransactions(this.events);
-    if (openTransactions.some((transaction) => transaction.state === 'invalid')) {
-      throw new Error('Context compaction is blocked by an invalid transactional generation sequence.');
-    }
-    let coveredEvents: TAgentEvent[];
-    if (openTransactions.length > 0) {
-      if (reason === 'retention') return undefined;
-      if (reason !== 'context-overflow') {
-        throw new Error('Context compaction is blocked while a transactional generation is open.');
-      }
-      const openGenerationIds = new Set(
-        openTransactions.map((transaction) => transaction.generationId),
-      );
-      const firstOpenIndex = this.events.findIndex((event) =>
-        !!event.generationId && openGenerationIds.has(event.generationId));
-      coveredEvents = firstOpenIndex < 0 ? [] : this.events.slice(0, firstOpenIndex);
-    } else {
-      coveredEvents = this.events.slice();
-    }
-    if (coveredEvents.length === 0) return undefined;
-    const visibleCoveredEvents = filterModelVisibleAgentEvents(coveredEvents);
-    const messages = this.buildContext(visibleCoveredEvents);
-    const replacementMessages = this.options.contextCompactor
-      ? await this.invokeGenerationCallback(
-          () => this.options.contextCompactor!(messages, visibleCoveredEvents, { abortSignal, reason }),
-        )
-      : reason === 'context-overflow' && this.options.onContextOverflow
-        ? await this.invokeGenerationCallback(
-            () => this.options.onContextOverflow!(messages, { abortSignal }),
-          )
-        : undefined;
-    if (!replacementMessages) {
-      throw new ContextOverflowError('Agent context compaction requires a contextCompactor.');
-    }
-    abortSignal?.throwIfAborted();
-    const archivedTransactionMap = new Map<string, IArchivedAgentGenerationTransaction>();
-    const rememberArchivedTransaction = (transaction: IArchivedAgentGenerationTransaction): void => {
-      archivedTransactionMap.delete(transaction.generationId);
-      archivedTransactionMap.set(transaction.generationId, transaction);
-    };
-    for (const event of coveredEvents) {
-      if (event.type !== 'context-compaction') continue;
-      for (const transaction of event.archivedTransactions ?? []) {
-        rememberArchivedTransaction(transaction);
-      }
-    }
-    const coveredTransactions = getAgentGenerationTransactions(coveredEvents);
-    for (const event of coveredEvents) {
-      if (event.type !== 'generation-outcome') continue;
-      const transaction = coveredTransactions.get(event.generationId);
-      if (!transaction || transaction.state === 'invalid') continue;
-      rememberArchivedTransaction({
-        generationId: transaction.generationId,
-        claimTokenDigest: transaction.begun.claimTokenDigest,
-        outcome: event.outcome,
-      });
-    }
-    const archivedTransactions = [...archivedTransactionMap.values()]
-      .slice(-(this.options.maxArchivedTransactionTombstones ?? 1000));
-    const compaction = this.commitEvent(createAgentEvent<IContextCompactionEvent>({
-      type: 'context-compaction',
-      coveredEventIds: coveredEvents.map((event) => event.id),
-      replacementEvents: modelMessagesToAgentEvents(replacementMessages),
-      archivedTransactions: archivedTransactions.length > 0
-        ? archivedTransactions
-        : undefined,
-      parentIds: [coveredEvents[coveredEvents.length - 1].id],
-    }));
-    await this.flushPersistence();
-    return compaction;
-  }
-
-  private queueExclusive<TValue>(operation: () => Promise<TValue>): Promise<TValue> {
-    const run = this.generationQueue.then(() => {
-      if (this.closed) throw new Error('AgentSession is closed.');
-      if (this.maintenanceError !== undefined) throw this.maintenanceError;
-      return operation();
-    });
-    this.generationQueue = run.then(() => undefined, () => undefined);
-    return run;
-  }
-
-  public compact(options: IAgentCompactOptions = {}): Promise<void> {
-    const combinedAbort = combineAbortSignals([options.abort, this.sessionAbortController.signal]);
-    const operation = this.queueExclusive(async () => {
-      combinedAbort.signal.throwIfAborted();
-      await this.performCompaction(options.reason ?? 'manual', combinedAbort.signal);
-    }).finally(combinedAbort.cleanup);
-    return waitWithAbort(operation, [options.abort, this.sessionAbortController.signal]);
-  }
-
-  public archiveCompactedEvents(
-    compactionEventId?: string,
-  ): Promise<TAgentEventArchive | undefined> {
-    return this.queueExclusive(() => this.archiveCompactedEventsLocked(compactionEventId));
-  }
-
-  private async archiveCompactedEventsLocked(
-    compactionEventId?: string,
-  ): Promise<TAgentEventArchive | undefined> {
-    if (getOpenAgentGenerationTransactions(this.events).length > 0) {
-      throw new Error('Archival is blocked while a transactional generation is open.');
-    }
-    if (getUncertainToolExecutionIntents(this.events).length > 0) {
-      throw new Error('Archival is blocked by unresolved tool execution intents.');
-    }
-    const eventStore = this.options.eventStore;
-    if (!eventStore?.archive) {
-      throw new Error('Archival requires an eventStore with archive support.');
-    }
-    const compaction = compactionEventId
-      ? this.events.find((event) => event.id === compactionEventId)
-      : [...this.events].reverse().find((event) => event.type === 'context-compaction');
-    if (!compaction || compaction.type !== 'context-compaction') return undefined;
-    const coveredIds = new Set(compaction.coveredEventIds);
-    const archivedEvents = this.events.filter((event) => coveredIds.has(event.id));
-    if (archivedEvents.length === 0) {
-      return isAgentEventStoreV2(eventStore)
-        ? eventStore.loadArchive?.(this.options.sessionId!, compaction.id)
-        : eventStore.loadArchive?.(this.options.sessionId!, compaction.id);
-    }
-    const archiveBase = {
-      sessionId: this.options.sessionId!,
-      archiveId: compaction.id,
-      createdAt: Date.now(),
-      events: structuredClone(archivedEvents),
-    };
-    const archive: TAgentEventArchive = isAgentEventStoreV2(eventStore)
-      ? { ...archiveBase, schemaVersion: 2 }
-      : { ...archiveBase, schemaVersion: 1 };
-    await this.flushPersistence();
-    if (isAgentEventStoreV2(eventStore)) {
-      await eventStore.archive?.(archive as IAgentEventArchiveV2);
-    } else {
-      await eventStore.archive?.(archive as IAgentEventArchive);
-    }
-    this.events.splice(0, this.events.length, ...this.events.filter((event) => !coveredIds.has(event.id)));
-    for (const event of archivedEvents) this.eventIds.delete(event.id);
-    const durability = this.queuePersistence();
-    this.queueNotification({ type: 'archived', events: archivedEvents }, durability);
-    await durability;
-    return archive;
-  }
-
-  private async runEventRetentionLocked(): Promise<void> {
-    const retention = this.options.eventRetention;
-    if (!retention) return;
-    if (
-      getOpenAgentGenerationTransactions(this.events).length > 0
-      || getUncertainToolExecutionIntents(this.events).length > 0
-    ) return;
-    while (this.events.length > retention.maxEvents) {
-      const compaction = await this.performCompaction(
-        'retention',
-        this.sessionAbortController.signal,
-      );
-      if (!compaction) return;
-      await this.archiveCompactedEventsLocked(compaction.id);
-    }
-  }
-
-  private scheduleEventRetention(): void {
-    const retention = this.options.eventRetention;
-    if (
-      !retention
-      || this.events.length <= retention.maxEvents
-      || this.retentionPromise
-      || this.closed
-    ) return;
-    const operation = this.generationQueue.then(() => {
-      if (this.maintenanceError !== undefined) throw this.maintenanceError;
-      return this.runEventRetentionLocked();
-    });
-    this.generationQueue = operation.then(() => undefined, () => undefined);
-    this.retentionPromise = operation;
-    void operation.then(
-      () => {
-        if (this.retentionPromise === operation) this.retentionPromise = undefined;
-      },
-      (error) => {
-        const expectedCloseAbort = this.closed
-          && (error === this.sessionAbortController.signal.reason
-            || (error instanceof DOMException && error.name === 'AbortError'));
-        if (!expectedCloseAbort) this.maintenanceError ??= error;
-        if (this.retentionPromise === operation) this.retentionPromise = undefined;
-      },
-    );
-  }
-
-  private eventsByIds(ids: ReadonlySet<string>): TAgentEvent[] {
-    return this.events.filter((event) => ids.has(event.id));
-  }
-
-  private currentGenerationEvent(
-    generationId: string,
-    type: 'tool-call' | 'tool-result',
-    toolCallId: string,
-    inferenceId?: string,
-  ): IToolCallEvent | IToolResultEvent | undefined {
-    return this.events.find((event) =>
-      event.generationId === generationId
-      && event.type === type
-      && event.toolCallId === toolCallId
-      && (inferenceId === undefined || event.inferenceId === inferenceId),
-    ) as IToolCallEvent | IToolResultEvent | undefined;
-  }
-
-  private reconcileToolResult(
-    generationId: string,
-    modelEvent: IToolResultEvent,
-  ): void {
-    const existingIndex = this.events.findIndex((event) =>
-      event.generationId === generationId
-      && event.type === 'tool-result'
-      && event.toolCallId === modelEvent.toolCallId
-      && event.inferenceId === modelEvent.inferenceId,
-    );
-    let provisionalIndex = existingIndex;
-    if (provisionalIndex === -1) {
-      for (let index = this.events.length - 1; index >= 0; index--) {
-        const event = this.events[index];
-        if (
-          event.generationId === generationId
-          && event.type === 'tool-result'
-          && event.toolCallId === modelEvent.toolCallId
-          && event.responseMessageCommitted !== true
-        ) {
-          provisionalIndex = index;
-          break;
-        }
-      }
-    }
-    if (provisionalIndex === -1) {
-      this.commitEvent(modelEvent);
-      return;
-    }
-    const existing = this.events[provisionalIndex] as IToolResultEvent;
-    this.events[provisionalIndex] = {
-      ...existing,
-      modelOutput: modelEvent.modelOutput,
-      responseMessageCommitted: true,
-      providerOptions: modelEvent.providerOptions,
-      messageProviderOptions: modelEvent.messageProviderOptions,
-    };
-    const updatedEvent = this.events[provisionalIndex];
-    const durability = this.queuePersistence();
-    this.queueNotification({ type: 'updated', events: [updatedEvent] }, durability);
-  }
-
-  private commitResponseMessages(
-    messages: readonly plugins.ModelMessage[],
-    generationId: string,
-    inferenceId: string,
-    executionIntentIds: ReadonlyMap<string, string>,
-  ): void {
-    const convertedEvents = modelMessagesToAgentEvents(messages, {
-      causationId: inferenceId,
-      generationId,
-      inferenceId,
-    });
-    for (const event of convertedEvents) {
-      if (event.type === 'tool-call') {
-        if (!this.currentGenerationEvent(
-          generationId,
-          'tool-call',
-          event.toolCallId,
-          inferenceId,
-        )) {
-          this.commitEvent(event);
-        }
-      } else if (event.type === 'tool-result') {
-        const executionIntentId = event.executionIntentId
-          ?? executionIntentIds.get(event.toolCallId);
-        this.reconcileToolResult(
-          generationId,
-          executionIntentId ? { ...event, executionIntentId } : event,
-        );
-      } else {
-        this.commitEvent(event);
-      }
-    }
-  }
-
-  private wrapToolsForGeneration(
-    generationId: string,
-    tools: plugins.ToolSet,
-    preparations: Map<string, IToolCallPreparationLedgerEntry>,
-    completedPreparations: ReadonlySet<string>,
-    preparationErrors: ReadonlyMap<string, unknown>,
-    ledger: Map<string, IToolExecutionLedgerEntry>,
-    getMessages: () => plugins.ModelMessage[],
-  ): plugins.ToolSet {
-    const wrappedTools: plugins.ToolSet = {};
-    for (const [toolName, toolDefinition] of Object.entries(tools)) {
-      const executableTool = toolDefinition as typeof toolDefinition & {
-        execute?: (input: unknown, options: plugins.ToolExecutionOptions<unknown>) => unknown;
-      };
-      if (!executableTool.execute) {
-        wrappedTools[toolName] = toolDefinition;
-        continue;
-      }
-      const originalExecute = executableTool.execute.bind(executableTool);
-      wrappedTools[toolName] = {
-        ...toolDefinition,
-        execute: (input: unknown, executionOptions: plugins.ToolExecutionOptions<unknown>) => {
-          const toolCallId = executionOptions.toolCallId;
-          const signature = toolSignature(toolName, input);
-          const preparation = preparations.get(toolCallId);
-          if (!preparation) {
-            throw new Error(
-              `Tool call "${toolCallId}" executed before preparation in generation "${generationId}".`,
-            );
-          }
-          if (preparation.signature !== signature) {
-            throw new Error(`Tool call id collision for "${toolCallId}" in generation "${generationId}".`);
-          }
-          if (!completedPreparations.has(toolCallId)) {
-            throw preparationErrors.get(toolCallId)
-              ?? new Error(
-                `Tool call "${toolCallId}" executed before preparation completed in generation "${generationId}".`,
-              );
-          }
-          const existing = ledger.get(toolCallId);
-          if (existing) {
-            if (existing.signature !== signature) {
-              throw new Error(`Tool call id collision for "${toolCallId}" in generation "${generationId}".`);
-            }
-            return existing.promise;
-          }
-          const contextualExecutionOptions = {
-            ...executionOptions,
-            messages: getMessages(),
-          };
-          let resolveCompletion!: (output: unknown) => void;
-          let rejectCompletion!: (error: unknown) => void;
-          const promise = new Promise<unknown>((resolve, reject) => {
-            resolveCompletion = resolve;
-            rejectCompletion = reject;
-          });
-          void promise.catch(() => undefined);
-          ledger.set(toolCallId, { signature, promise });
-          try {
-            const result = this.invokeGenerationCallback(
-              () => originalExecute(input, contextualExecutionOptions),
-            );
-            if (isAsyncIterable(result)) {
-              return this.trackToolExecutionIterable(
-                result,
-                resolveCompletion,
-                rejectCompletion,
-              );
-            }
-            if (isPromiseLike(result)) {
-              const deferredIterable = (async function* () {
-                const output = await result;
-                if (isAsyncIterable(output)) {
-                  yield* output;
-                } else {
-                  yield output;
-                }
-              })();
-              return this.trackToolExecutionIterable(
-                deferredIterable,
-                resolveCompletion,
-                rejectCompletion,
-              );
-            }
-            resolveCompletion(result);
-            return result;
-          } catch (error) {
-            rejectCompletion(error);
-            throw error;
-          }
-        },
-      } as typeof toolDefinition;
-    }
-    wrappedTools.invalid = plugins.tool({
-      description: 'Sink for unrecognised tool calls; returns an error message to the model',
-      inputSchema: plugins.z.object({ tool: plugins.z.string(), error: plugins.z.string() }),
-      execute: async ({ tool, error }: { tool: string; error: string }) =>
-        `Unknown tool "${tool}": ${error}`,
-    });
-    return wrappedTools;
-  }
-
-  private trackToolExecutionIterable(
-    iterable: AsyncIterable<unknown>,
-    resolveCompletion: (output: unknown) => void,
-    rejectCompletion: (error: unknown) => void,
-  ): AsyncIterable<unknown> {
-    const iterator = iterable[Symbol.asyncIterator]();
-    let settled = false;
-    let lastOutput: unknown;
-    const settleSuccess = () => {
-      if (settled) return;
-      settled = true;
-      resolveCompletion(lastOutput);
-    };
-    const settleError = (error: unknown) => {
-      if (settled) return;
-      settled = true;
-      rejectCompletion(error);
-    };
-    const incompleteError = () => new Error(
-      'Tool execution stream ended before normal completion.',
-    );
-    const observe = (
-      operation: () => Promise<IteratorResult<unknown>>,
-      cacheOutput: boolean,
-      rejectWhenDone = false,
-    ): Promise<IteratorResult<unknown>> => {
-      let operationResult: Promise<IteratorResult<unknown>>;
-      try {
-        operationResult = Promise.resolve(operation());
-      } catch (error) {
-        settleError(error);
-        return Promise.reject(error);
-      }
-      return operationResult.then(
-        (result) => {
-          if (!result.done && cacheOutput) lastOutput = result.value;
-          if (result.done) {
-            if (rejectWhenDone) settleError(incompleteError());
-            else settleSuccess();
-          }
-          return result;
-        },
-        (error) => {
-          settleError(error);
-          throw error;
-        },
-      );
-    };
-    const wrappedIterator: AsyncIterator<unknown, unknown, unknown> & AsyncIterable<unknown> = {
-      next: (...args: [] | [unknown]) => observe(() => iterator.next(...args), true),
-      return: iterator.return
-        ? (...args: [] | [unknown]) => {
-            let returnResult: Promise<IteratorResult<unknown>>;
-            try {
-              returnResult = Promise.resolve(iterator.return!(...args));
-              settleError(incompleteError());
-            } catch (error) {
-              settleError(error);
-              return Promise.reject(error);
-            }
-            return returnResult.then(
-              (result) => result,
-              (error) => {
-                settleError(error);
-                throw error;
-              },
-            );
-          }
-        : async (...args: [] | [unknown]) => {
-            settleError(incompleteError());
-            return { done: true, value: args[0] };
-          },
-      throw: iterator.throw
-        ? (error?: unknown) => observe(() => iterator.throw!(error), true, true)
-        : async (error?: unknown) => {
-            settleError(error);
-            throw error;
-          },
-      [Symbol.asyncIterator]() {
-        return this;
-      },
-    };
-    return wrappedIterator;
-  }
-
-  private ownGenerationLeaseCleanup(
-    lease: IAgentGenerationLease | undefined,
-  ): IGenerationLeaseCleanupOwnership | undefined {
-    if (!lease?.close) return undefined;
-    const ownership: IGenerationLeaseCleanupOwnership = { lease, settled: false };
-    this.unresolvedLeaseCleanups.add(ownership);
-    return ownership;
-  }
-
-  private async cleanupGenerationLease(
-    ownership: IGenerationLeaseCleanupOwnership,
-  ): Promise<void> {
-    if (ownership.settled) return;
-    const timeoutMs = this.options.generationLeaseCleanupTimeoutMs ?? 30_000;
-    const timeoutError = new Error(`Generation lease cleanup timed out after ${timeoutMs}ms.`);
-    let timer: NodeJS.Timeout | undefined;
-    const closePromise = Promise.resolve().then(() =>
-      this.invokeGenerationCallback(() => ownership.lease.close!()));
-    void closePromise.then(
-      () => {
-        ownership.settled = true;
-        this.unresolvedLeaseCleanups.delete(ownership);
-        this.refreshCloseCleanupCompleted();
-      },
-      () => undefined,
-    );
-    const timeoutPromise = new Promise<never>((_resolve, reject) => {
-      timer = setTimeout(() => reject(timeoutError), timeoutMs);
-    });
-    try {
-      await Promise.race([closePromise, timeoutPromise]);
-      ownership.settled = true;
-      this.unresolvedLeaseCleanups.delete(ownership);
-    } catch (error) {
-      throw new AgentGenerationLeaseCleanupError(
-        ownership.lease,
-        error,
-        () => this.cleanupGenerationLease(ownership),
-      );
-    } finally {
-      if (timer) clearTimeout(timer);
-    }
-  }
-
-  public generate(options: IAgentGenerateOptions = {}): Promise<IAgentGenerateResult> {
-    const capabilityError = options.transaction
-      ? this.transactionalStoreCapabilityError()
-      : undefined;
-    if (capabilityError) return Promise.reject(capabilityError);
-    const run = this.generationQueue.then(async () => {
-      if (!options.transaction) options.abort?.throwIfAborted();
-      if (!options.transaction && this.sessionAbortController.signal.aborted) {
-        throw this.sessionAbortController.signal.reason
-          ?? new DOMException('Agent session aborted', 'AbortError');
-      }
-      if (this.closed) throw new Error('AgentSession is closed.');
-      if (this.maintenanceError !== undefined) throw this.maintenanceError;
-      await this.runEventRetentionLocked();
-      return this.generateLocked(options);
-    });
-    this.generationQueue = run.then(() => undefined, () => undefined);
-    return options.transaction
-      ? run
-      : waitWithAbort(run, [options.abort, this.sessionAbortController.signal]);
-  }
-
-  private resolveEffectiveGenerationRuntime(
-    options: IAgentGenerateOptions,
-    lease: IAgentGenerationLease | undefined,
-  ): IEffectiveGenerationRuntime {
-    const model = lease?.model ?? options.model ?? this.options.model;
-    if (!model) {
-      throw new Error(
-        'Agent generation requires a model from its prepared lease, generate options, or session defaults.',
-      );
-    }
-    const system = lease?.system ?? options.system ?? this.options.system;
-    const tools = lease?.tools ?? options.tools ?? this.options.tools ?? {};
-    if (Object.prototype.hasOwnProperty.call(tools, 'invalid')) {
-      throw new Error('Tool name "invalid" is reserved for SmartAgent tool-call repair.');
-    }
-    const providerOptions = lease?.providerOptions
-      ?? options.providerOptions
-      ?? this.options.providerOptions;
-    const cache = lease?.cache ?? options.cache ?? this.options.cache ?? 'auto';
-    const maxSteps = lease?.maxSteps ?? options.maxSteps ?? this.options.maxSteps ?? 20;
-    if (!Number.isSafeInteger(maxSteps) || maxSteps <= 0) {
-      throw new Error('maxSteps must be a positive integer.');
-    }
-    const configuredCacheProvider = typeof cache === 'object' ? cache.provider : undefined;
-    const messageCacheProvider = cache === false
-      ? undefined
-      : configuredCacheProvider
-        ?? plugins.resolveSmartAiCacheProvider(model.provider, model.modelId);
-    const effectiveModel = messageCacheProvider
-      ? plugins.wrapLanguageModel({
-          model,
-          middleware: plugins.createSmartAiCachingMiddleware({
-            ...(typeof cache === 'object' ? cache : {}),
-            provider: messageCacheProvider,
-          }),
-        })
-      : model;
-    return {
-      model: effectiveModel,
-      system,
-      tools,
-      providerOptions: plugins.applySmartAiCacheProviderOptions({
-        provider: model.provider,
-        modelId: model.modelId,
-        providerOptions,
-        cache,
-        sessionId: this.options.sessionId,
-      }),
-      maxSteps,
-    };
-  }
-
-  private async generateLocked(options: IAgentGenerateOptions): Promise<IAgentGenerateResult> {
-    await this.flushPersistence();
-    const maxContextOverflowRetries = this.options.maxContextOverflowRetries ?? 3;
-    const generationId = options.transaction?.generationId ?? createAgentEventId('generation');
-    const generationAbortController = new AbortController();
-    this.currentGenerationAbortController = generationAbortController;
-    const combinedAbort = combineAbortSignals([
-      this.sessionAbortController.signal,
-      generationAbortController.signal,
-      options.abort,
-    ]);
-
-    let lease: IAgentGenerationLease | undefined;
-    let leaseCleanupOwnership: IGenerationLeaseCleanupOwnership | undefined;
-    let operationError: unknown;
-    let completedResult: IAgentGenerateResult | undefined;
-    let transactionExecutionStarted = false;
-    try {
-      if (options.transaction) {
-        const transaction = this.verifyGenerationClaim(options.transaction);
-        if (!('begun' in transaction) || transaction.state !== 'begun') {
-          const transactionState = 'begun' in transaction
-            ? transaction.state
-            : transaction.outcome;
-          throw new Error(
-            `Transactional generation "${generationId}" cannot execute from state "${transactionState}".`,
-          );
-        }
-        this.commitEvent(createAgentEvent<IGenerationExecutionStartedEvent>({
-          type: 'generation-execution-started',
-          generationId,
-          parentIds: [transaction.begun.id],
-        }));
-        await this.flushPersistence();
-        transactionExecutionStarted = true;
-      }
-      combinedAbort.signal.throwIfAborted();
-      lease = options.prepare
-        ? await this.invokeGenerationCallback(
-            () => options.prepare!({ generationId, abortSignal: combinedAbort.signal }),
-          )
-        : undefined;
-      leaseCleanupOwnership = this.ownGenerationLeaseCleanup(lease);
-      combinedAbort.signal.throwIfAborted();
-      const runtime = this.resolveEffectiveGenerationRuntime(options, lease);
-      const maxSteps = runtime.maxSteps;
-
-      let stepCount = 0;
-      let attempt = 0;
-      let contextOverflowRetries = 0;
-      let totalInput = 0;
-      let totalOutput = 0;
-      let totalCacheRead = 0;
-      let totalCacheWrite = 0;
-      let currentInferenceId: string | undefined;
-      let latestInferenceVisibleIds = new Set(this.events.map((event) => event.id));
-      const completedInferenceIds = new Set<string>();
-      const reasoningTextById = new Map<string, string>();
-      const toolCalls: IAgentToolCallRecord[] = [];
-      const toolCallIndexes = new Map<string, number>();
-      const preparations = new Map<string, IToolCallPreparationLedgerEntry>();
-      const completedPreparations = new Set<string>();
-      const preparationErrors = new Map<string, unknown>();
-      const ledger = new Map<string, IToolExecutionLedgerEntry>();
-      const executionIntentIds = new Map<string, string>();
-      const preliminaryToolOutputs = new Map<string, IAgentToolCallUpdateEvent>();
-
-      const beginInference = async (): Promise<string> => {
-        const marker = this.commitEvent(createAgentEvent<IRuntimeEvent>({
-          type: 'runtime-event',
-          event: {
-            type: 'inference-started',
-            generationId,
-            completedSteps: stepCount,
-          },
-          modelVisible: false,
-          generationId,
-          parentIds: this.events.length > 0
-            ? [this.events[this.events.length - 1].id]
-            : undefined,
-        }));
-        currentInferenceId = marker.id;
-        latestInferenceVisibleIds = new Set(this.events.map((event) => event.id));
-        await this.flushPersistence();
-        return marker.id;
-      };
-      const allTools = this.wrapToolsForGeneration(
-        generationId,
-        runtime.tools,
-        preparations,
-        completedPreparations,
-        preparationErrors,
-        ledger,
-        () => this.buildContext(this.eventsByIds(latestInferenceVisibleIds)),
-      );
-
-      const flushReasoning = (): void => {
-        for (const [id, reasoningText] of reasoningTextById) {
-          this.options.onReasoningEnd?.(id, reasoningText);
-        }
-        reasoningTextById.clear();
-      };
-
-      while (true) {
-        const remainingSteps = maxSteps - stepCount;
-        if (remainingSteps <= 0) {
-          throw new Error(`Agent generation exhausted its ${maxSteps} step limit during retry.`);
-        }
-        let streamError: unknown;
-        try {
-          currentInferenceId = undefined;
-          const result = plugins.streamText({
-            model: runtime.model,
-            instructions: runtime.system,
-            messages: this.getModelMessages(),
-            allowSystemInMessages: true,
-            tools: allTools,
-            providerOptions: runtime.providerOptions,
-            stopWhen: plugins.stepCountIs(remainingSteps),
-            maxRetries: 0,
-            abortSignal: combinedAbort.signal,
-            prepareStep: async () => {
-              await beginInference();
-              return { messages: this.buildContext(this.eventsByIds(latestInferenceVisibleIds)) };
-            },
-            onError: ({ error }) => {
-              streamError = error;
-            },
-            repairToolCall: async ({ toolCall, tools: availableTools, error }) => {
-              const lowerName = toolCall.toolName.toLowerCase();
-              if (
-                lowerName !== toolCall.toolName
-                && Object.prototype.hasOwnProperty.call(availableTools, lowerName)
-              ) {
-                return { ...toolCall, toolName: lowerName };
-              }
-              return {
-                ...toolCall,
-                toolName: 'invalid',
-                input: JSON.stringify({ tool: toolCall.toolName, error: String(error) }),
-              };
-            },
-            onChunk: ({ chunk }) => {
-              const chunkType = String((chunk as { type?: unknown }).type ?? '');
-              if (chunkType === 'text-delta') {
-                const textChunk = chunk as { delta?: string; textDelta?: string; text?: string };
-                this.options.onToken?.(textChunk.delta ?? textChunk.textDelta ?? textChunk.text ?? '');
-                return;
-              }
-              if (chunkType === 'tool-result') {
-                const toolResultChunk = chunk as {
-                  preliminary?: boolean;
-                  toolCallId: string;
-                  toolName: string;
-                  input: unknown;
-                  output: unknown;
-                };
-                if (toolResultChunk.preliminary === true) {
-                  const previous = preliminaryToolOutputs.get(toolResultChunk.toolCallId);
-                  if (!previous || !plugins.isDeepStrictEqual(previous.output, toolResultChunk.output)) {
-                    const event: IAgentToolCallUpdateEvent = {
-                      toolCallId: toolResultChunk.toolCallId,
-                      toolName: toolResultChunk.toolName,
-                      input: toolResultChunk.input,
-                      output: toolResultChunk.output,
-                    };
-                    preliminaryToolOutputs.set(toolResultChunk.toolCallId, event);
-                    this.options.onToolCallUpdate?.(event);
-                  }
-                }
-                return;
-              }
-              const reasoningChunk = chunk as {
-                id?: string;
-                delta?: string;
-                textDelta?: string;
-                text?: string;
-                providerMetadata?: unknown;
-              };
-              const id = reasoningChunk.id ?? 'reasoning';
-              if (chunkType === 'reasoning-start') {
-                reasoningTextById.set(id, '');
-                this.options.onReasoningStart?.(id, reasoningChunk.providerMetadata);
-              } else if (chunkType === 'reasoning-delta') {
-                const delta = reasoningChunk.delta ?? reasoningChunk.textDelta ?? reasoningChunk.text ?? '';
-                if (!reasoningTextById.has(id)) {
-                  reasoningTextById.set(id, '');
-                  this.options.onReasoningStart?.(id, reasoningChunk.providerMetadata);
-                }
-                reasoningTextById.set(id, (reasoningTextById.get(id) ?? '') + delta);
-                this.options.onReasoningDelta?.(id, delta, reasoningChunk.providerMetadata);
-              } else if (chunkType === 'reasoning-end') {
-                const text = reasoningTextById.get(id) ?? '';
-                reasoningTextById.delete(id);
-                this.options.onReasoningEnd?.(id, text, reasoningChunk.providerMetadata);
-              }
-            },
-            onToolExecutionStart: ({ toolCall }) => {
-              const input = parseToolInput(toolCall.input);
-              const signature = toolSignature(toolCall.toolName, input);
-              const existing = preparations.get(toolCall.toolCallId);
-              if (existing) {
-                if (existing.signature !== signature) {
-                  throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
-                }
-                return existing.promise;
-              }
-              const promise = Promise.resolve().then(async () => {
-                const startedBeforeInference = !currentInferenceId;
-                const inferenceId = currentInferenceId ?? await beginInference();
-                const approvalAssistantEvent = startedBeforeInference
-                  ? [...this.events].reverse().find((candidate): candidate is IAssistantMessageEvent =>
-                      candidate.type === 'assistant-message'
-                      && Array.isArray(candidate.content)
-                      && candidate.content.some((part) =>
-                        part.type === 'tool-call' && part.toolCallId === toolCall.toolCallId,
-                      ),
-                    )
-                  : undefined;
-                let callEvent = [...this.events].reverse().find((event): event is IToolCallEvent =>
-                  event.type === 'tool-call'
-                  && event.toolCallId === toolCall.toolCallId
-                  && (
-                    event.generationId === generationId
-                    || (
-                      !!approvalAssistantEvent?.id
-                      && event.parentIds?.includes(approvalAssistantEvent.id) === true
-                    )
-                  ));
-                if (callEvent && toolSignature(callEvent.toolName, callEvent.input) !== signature) {
-                  throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
-                }
-                if (!callEvent) {
-                  callEvent = this.commitEvent(createAgentEvent<IToolCallEvent>({
-                    type: 'tool-call',
-                    toolCallId: toolCall.toolCallId,
-                    toolName: toolCall.toolName,
-                    input,
-                    generationId,
-                    inferenceId,
-                    causationId: inferenceId,
-                    parentIds: [inferenceId],
-                  }));
-                }
-                await this.flushPersistence();
-                recordToolCall(toolCalls, toolCallIndexes, toolCall);
-                if (options.transaction) {
-                  let intent = [...this.events].reverse().find(
-                    (event): event is IToolExecutionIntentEvent =>
-                      event.type === 'tool-execution-intent'
-                      && event.generationId === generationId
-                      && event.toolCallId === toolCall.toolCallId,
-                  );
-                  if (intent && toolSignature(intent.toolName, intent.input) !== signature) {
-                    throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
-                  }
-                  if (!intent) {
-                    intent = this.commitEvent(createAgentEvent<IToolExecutionIntentEvent>({
-                      type: 'tool-execution-intent',
-                      generationId,
-                      inferenceId: callEvent.inferenceId,
-                      causationId: callEvent.id,
-                      toolCallId: toolCall.toolCallId,
-                      toolName: toolCall.toolName,
-                      input,
-                      parentIds: [callEvent.id],
-                    }));
-                  }
-                  executionIntentIds.set(toolCall.toolCallId, intent.id);
-                  await this.flushPersistence();
-                }
-                completedPreparations.add(toolCall.toolCallId);
-                const callbackEvent: IAgentToolCallStartEvent = {
-                  toolCallId: toolCall.toolCallId,
-                  toolName: toolCall.toolName,
-                  input,
-                };
-                this.options.onToolCallStart?.(callbackEvent);
-                this.options.onToolCall?.(callbackEvent.toolName, callbackEvent.input);
-              });
-              preparations.set(toolCall.toolCallId, { signature, promise });
-              void promise.catch((error) => {
-                if (!completedPreparations.has(toolCall.toolCallId)) {
-                  preparationErrors.set(toolCall.toolCallId, error);
-                }
-              });
-              return promise;
-            },
-            onToolExecutionEnd: async (finish) => {
-              preliminaryToolOutputs.delete(finish.toolCall.toolCallId);
-              const inferenceId = currentInferenceId ?? await beginInference();
-              const previousResult = this.currentGenerationEvent(
-                generationId,
-                'tool-result',
-                finish.toolCall.toolCallId,
-              );
-              if (this.currentGenerationEvent(
-                generationId,
-                'tool-result',
-                finish.toolCall.toolCallId,
-                inferenceId,
-              )) return;
-              const input = parseToolInput(finish.toolCall.input);
-              const startEvent: IAgentToolCallStartEvent = {
-                toolCallId: finish.toolCall.toolCallId,
-                toolName: finish.toolCall.toolName,
-                input,
-              };
-              const finishEvent: TAgentToolCallFinishEvent = finish.toolOutput.type === 'tool-result'
-                ? { ...startEvent, success: true, output: finish.toolOutput.output }
-                : { ...startEvent, success: false, error: errorToString(finish.toolOutput.error) };
-              const parentCall = this.currentGenerationEvent(
-                generationId,
-                'tool-call',
-                finish.toolCall.toolCallId,
-                inferenceId,
-              );
-              const toolWithModelOutput = allTools[finish.toolCall.toolName] as {
-                toModelOutput?: (options: {
-                  toolCallId: string;
-                  input: unknown;
-                  output: unknown;
-                }) => Promise<TAgentToolResultOutput> | TAgentToolResultOutput;
-              } | undefined;
-              const modelOutput = finishEvent.success && toolWithModelOutput?.toModelOutput
-                ? await this.invokeGenerationCallback(
-                    () => toolWithModelOutput.toModelOutput!({
-                      toolCallId: finish.toolCall.toolCallId,
-                      input,
-                      output: finishEvent.output,
-                    }),
-                  )
-                : fallbackModelOutput(
-                    finishEvent.success ? finishEvent.output : undefined,
-                    finishEvent.success ? undefined : finishEvent.error,
-                  );
-              const executionIntentId = executionIntentIds.get(finish.toolCall.toolCallId);
-              this.commitEvent(createAgentEvent<IToolResultEvent>({
-                type: 'tool-result',
-                toolCallId: finish.toolCall.toolCallId,
-                toolName: finish.toolCall.toolName,
-                ...(executionIntentId ? { executionIntentId } : {}),
-                output: finishEvent.success ? finishEvent.output : undefined,
-                error: finishEvent.success ? undefined : finishEvent.error,
-                modelOutput,
-                generationId,
-                inferenceId,
-                causationId: inferenceId,
-                parentIds: parentCall ? [parentCall.id] : [inferenceId],
-              }));
-              await this.flushPersistence();
-              recordToolCall(
-                toolCalls,
-                toolCallIndexes,
-                finish.toolCall,
-                finishEvent.success ? { output: finishEvent.output } : { error: finishEvent.error },
-              );
-              if (previousResult) return;
-              this.options.onToolCallFinish?.(finishEvent);
-              this.options.onToolResult?.(
-                finishEvent.toolName,
-                finishEvent.success ? finishEvent.output : undefined,
-              );
-            },
-            onStepEnd: async (step) => {
-              if (!currentInferenceId) throw new Error('Model step finished outside an inference.');
-              if (!completedInferenceIds.has(currentInferenceId)) {
-                completedInferenceIds.add(currentInferenceId);
-                stepCount++;
-              }
-              totalInput += step.usage.inputTokens ?? 0;
-              totalOutput += step.usage.outputTokens ?? 0;
-              totalCacheRead += step.usage.inputTokenDetails.cacheReadTokens ?? 0;
-              totalCacheWrite += step.usage.inputTokenDetails.cacheWriteTokens ?? 0;
-              for (const toolCall of step.toolCalls) {
-                recordToolCall(toolCalls, toolCallIndexes, toolCall);
-              }
-              for (const toolResult of step.toolResults) {
-                recordToolCall(toolCalls, toolCallIndexes, toolResult, { output: toolResult.output });
-              }
-              for (const part of step.content) {
-                if (part.type === 'tool-error') {
-                  recordToolCall(toolCalls, toolCallIndexes, part, { error: part.error });
-                }
-              }
-              this.commitResponseMessages(
-                step.response.messages,
-                generationId,
-                currentInferenceId,
-                executionIntentIds,
-              );
-              await this.flushPersistence();
-              attempt = 0;
-              contextOverflowRetries = 0;
-            },
-          });
-
-          const text = await result.text;
-          const finishReason = await result.finishReason;
-          await result.response;
-          if (streamError) throw streamError;
-          flushReasoning();
-          await this.flushPersistence();
-
-          const resultVisibleIds = new Set(latestInferenceVisibleIds);
-          for (const event of this.events) {
-            if (event.generationId === generationId) resultVisibleIds.add(event.id);
-          }
-          const generationResult: IAgentGenerateResult = {
-            text,
-            messages: this.buildContext(this.eventsByIds(resultVisibleIds)),
-            steps: stepCount,
-            finishReason,
-            usage: {
-              inputTokens: totalInput,
-              outputTokens: totalOutput,
-              totalTokens: totalInput + totalOutput,
-              cacheReadTokens: totalCacheRead,
-              cacheWriteTokens: totalCacheWrite,
-            },
-            toolCalls,
-            events: this.getEvents(),
-          };
-          await this.runEventRetentionLocked();
-          generationResult.events = this.getEvents();
-          completedResult = generationResult;
-          return generationResult;
-        } catch (error) {
-          flushReasoning();
-          const effectiveError = streamError ?? error;
-          if (combinedAbort.signal.aborted) {
-            throw combinedAbort.signal.reason ?? new DOMException('Aborted', 'AbortError');
-          }
-          if (effectiveError instanceof DOMException && effectiveError.name === 'AbortError') {
-            throw effectiveError;
-          }
-
-          if (
-            currentInferenceId
-            && !completedInferenceIds.has(currentInferenceId)
-            && this.events.some((event) =>
-              event.generationId === generationId
-              && event.inferenceId === currentInferenceId
-              && event.type === 'tool-result',
-            )
-          ) {
-            completedInferenceIds.add(currentInferenceId);
-            stepCount++;
-          }
-
-          if (isRetryableError(effectiveError) && attempt < MAX_RETRY_ATTEMPTS && stepCount < maxSteps) {
-            attempt++;
-            const errorWithHeaders = effectiveError as {
-              responseHeaders?: Record<string, string>;
-              headers?: Record<string, string>;
-            };
-            await sleep(
-              retryDelay(attempt, errorWithHeaders.responseHeaders ?? errorWithHeaders.headers),
-              combinedAbort.signal,
-            );
-            continue;
-          }
-
-          if (isContextOverflow(effectiveError)) {
-            if (!this.options.contextCompactor && !this.options.onContextOverflow) {
-              throw new ContextOverflowError();
-            }
-            if (contextOverflowRetries >= maxContextOverflowRetries) {
-              throw new ContextOverflowError(
-                `Agent context overflow persisted after ${maxContextOverflowRetries} compaction retries`,
-              );
-            }
-            combinedAbort.signal.throwIfAborted();
-            contextOverflowRetries++;
-            await this.performCompaction('context-overflow', combinedAbort.signal);
-            continue;
-          }
-          throw effectiveError;
-        }
-      }
-    } catch (error) {
-      operationError = error;
-    } finally {
-      let cleanupError: unknown;
-      if (leaseCleanupOwnership) {
-        try {
-          await this.cleanupGenerationLease(leaseCleanupOwnership);
-        } catch (error) {
-          cleanupError = error;
-        }
-      }
-      if (operationError === undefined && combinedAbort.signal.aborted) {
-        operationError = combinedAbort.signal.reason
-          ?? new DOMException('Aborted', 'AbortError');
-      }
-      let effectiveError = operationError !== undefined && cleanupError !== undefined
-        ? new AggregateError(
-            [operationError, cleanupError],
-            'Agent generation and generation lease cleanup both failed.',
-          )
-        : operationError ?? cleanupError;
-      try {
-        if (options.transaction && transactionExecutionStarted) {
-          if (effectiveError === undefined && combinedAbort.signal.aborted) {
-            effectiveError = combinedAbort.signal.reason
-              ?? new DOMException('Aborted', 'AbortError');
-          }
-          try {
-            if (effectiveError !== undefined) {
-              await this.appendGenerationOutcome(
-                generationId,
-                'interrupted',
-                this.transactionOutcomeErrorReason(effectiveError),
-              );
-            } else {
-              const transaction = this.transaction(generationId);
-              if (transaction.state !== 'execution-started') {
-                throw new Error(
-                  `Transactional generation "${generationId}" cannot complete from state "${transaction.state}".`,
-                );
-              }
-              combinedAbort.signal.throwIfAborted();
-              this.commitEvent(createAgentEvent<IGenerationExecutionCompletedEvent>({
-                type: 'generation-execution-completed',
-                generationId,
-                parentIds: [transaction.executionStarted!.id],
-              }));
-              await this.flushPersistence();
-              if (combinedAbort.signal.aborted) {
-                const abortError = combinedAbort.signal.reason
-                  ?? new DOMException('Aborted', 'AbortError');
-                await this.appendGenerationOutcome(
-                  generationId,
-                  'interrupted',
-                  this.transactionOutcomeErrorReason(abortError),
-                );
-                throw abortError;
-              }
-              if (completedResult) completedResult.events = this.getEvents();
-            }
-          } catch (outcomeError) {
-            if (effectiveError !== undefined) {
-              throw new AggregateError(
-                [effectiveError, outcomeError],
-                'Agent generation failed and its interrupted outcome could not be persisted.',
-              );
-            }
-            throw outcomeError;
-          }
-        }
-        if (effectiveError !== undefined) throw effectiveError;
-      } finally {
-        combinedAbort.cleanup();
-        if (this.currentGenerationAbortController === generationAbortController) {
-          this.currentGenerationAbortController = undefined;
-        }
-      }
-    }
-    throw operationError ?? new Error('Agent generation ended without a result.');
-  }
-
-  public abortCurrentGeneration(reason?: unknown): void {
-    this.currentGenerationAbortController?.abort(
-      reason ?? new DOMException('Current agent generation aborted', 'AbortError'),
-    );
-  }
-
-  public async abortSession(
-    reason?: unknown,
-    options: IAgentSessionAbortOptions = {},
-  ): Promise<void> {
-    if (!this.sessionAbortController.signal.aborted) {
-      this.sessionAbortController.abort(
-        reason ?? new DOMException('Agent session aborted', 'AbortError'),
-      );
-    }
-    this.abortCurrentGeneration(reason);
-    for (const key of [...this.scheduledGenerations.keys()]) {
-      this.cancelScheduledGeneration(
-        key,
-        reason ?? new DOMException('Agent session aborted', 'AbortError'),
-      );
-    }
-    if (options.abortBackgroundJobs) {
-      const jobs = this.options.executionContext?.jobs;
-      if (!jobs?.abort) return;
-      const runningJobs = (await jobs.list()).filter((job) => job.state === 'running');
-      await Promise.all(runningJobs.map((job) => jobs.abort!(job.executionId)));
-    }
-  }
-
-  public async getBackgroundExecution(executionId: string): Promise<plugins.IToolJobState> {
-    const jobs = this.options.executionContext?.jobs;
-    if (!jobs) throw new Error('This AgentSession has no background job context.');
-    return jobs.get(executionId);
-  }
-
-  public async abortBackgroundExecution(executionId: string): Promise<void> {
-    const jobs = this.options.executionContext?.jobs;
-    if (!jobs?.abort) throw new Error('This AgentSession cannot abort background jobs.');
-    await jobs.abort(executionId);
-  }
-
-  public async close(): Promise<void> {
-    if (this.generationCallbackContext.getStore()?.active) {
-      throw new Error(
-        'AgentSession.close() cannot be called from an active tool or compactor callback.',
-      );
-    }
-    this.closeFinalizationReached = false;
-    this.refreshCloseCleanupCompleted();
-    if (!this.closed) {
-      this.closed = true;
-      const closeReason = new DOMException('AgentSession closed', 'AbortError');
-      if (!this.sessionAbortController.signal.aborted) {
-        this.sessionAbortController.abort(closeReason);
-      }
-      this.abortCurrentGeneration(closeReason);
-      for (const key of [...this.scheduledGenerations.keys()]) {
-        this.cancelScheduledGeneration(key, closeReason);
-      }
-    }
-    let closeError: unknown;
-    const rememberCloseError = (error: unknown, message: string) => {
-      closeError = closeError === undefined
-        ? error
-        : new AggregateError([closeError, error], message);
-    };
-    try {
-      this.jobUnsubscribe?.();
-      this.jobUnsubscribe = undefined;
-    } catch (error) {
-      rememberCloseError(error, 'AgentSession close encountered multiple cleanup errors.');
-    }
-    try {
-      await this.generationQueue;
-      for (const transaction of getOpenAgentGenerationTransactions(this.events)) {
-        await this.appendGenerationOutcome(
-          transaction.generationId,
-          'interrupted',
-          'AgentSession closed before the transactional generation was finalized.',
-        );
-      }
-      if (this.retentionPromise) await this.retentionPromise;
-      await this.flushPersistence();
-      if (this.maintenanceError !== undefined) throw this.maintenanceError;
-    } catch (error) {
-      rememberCloseError(error, 'AgentSession close encountered persistence or maintenance errors.');
-    } finally {
-      for (const ownership of [...this.unresolvedLeaseCleanups]) {
-        try {
-          await this.cleanupGenerationLease(ownership);
-        } catch (error) {
-          rememberCloseError(error, 'AgentSession close encountered multiple cleanup errors.');
-        }
-      }
-      this.generationHandles.clear();
-      try {
-        while (this.notificationDispatches.size > 0) {
-          await Promise.all(this.notificationDispatches);
-        }
-      } catch (error) {
-        rememberCloseError(error, 'AgentSession close encountered notification cleanup errors.');
-      }
-      const listenerStates = [...this.listeners.values()];
-      this.listeners.clear();
-      try {
-        await Promise.all(listenerStates
-          .filter((state) => !state.executing && state.deliveryPromise)
-          .map((state) => state.deliveryPromise));
-      } catch (error) {
-        rememberCloseError(error, 'AgentSession close encountered listener cleanup errors.');
-      } finally {
-        this.closeFinalizationReached = true;
-        this.refreshCloseCleanupCompleted();
-      }
-    }
-    if (closeError !== undefined) throw closeError;
-  }
-
-  private invokeGenerationCallback<TValue>(callback: () => TValue): TValue {
-    const state: IGenerationCallbackState = { active: true };
-    return this.generationCallbackContext.run(state, () => {
-      try {
-        const result = callback();
-        return this.adoptGenerationCallbackResult(result, state) as TValue;
-      } catch (error) {
-        state.active = false;
-        throw error;
-      }
-    });
-  }
-
-  private adoptGenerationCallbackResult(
-    result: unknown,
-    state: IGenerationCallbackState,
-  ): unknown {
-    try {
-      if (isAsyncIterable(result)) {
-        return this.wrapGenerationCallbackIterable(result, state);
-      }
-      if (isPromiseLike(result)) {
-        return Promise.resolve(result).then(
-          (resolvedResult) => this.adoptGenerationCallbackResult(resolvedResult, state),
-          (error) => {
-            state.active = false;
-            throw error;
-          },
-        );
-      }
-      state.active = false;
-      return result;
-    } catch (error) {
-      state.active = false;
-      throw error;
-    }
-  }
-
-  private wrapGenerationCallbackIterable(
-    iterable: AsyncIterable<unknown>,
-    state: IGenerationCallbackState,
-  ): AsyncIterable<unknown> {
-    const iterator = this.generationCallbackContext.run(
-      state,
-      () => iterable[Symbol.asyncIterator](),
-    );
-    let settled = false;
-    const settle = () => {
-      if (settled) return;
-      settled = true;
-      state.active = false;
-    };
-    const invoke = (
-      operation: () => Promise<IteratorResult<unknown>>,
-    ): Promise<IteratorResult<unknown>> => {
-      let operationResult: Promise<IteratorResult<unknown>>;
-      try {
-        operationResult = this.generationCallbackContext.run(
-          state,
-          () => Promise.resolve(operation()),
-        );
-      } catch (error) {
-        settle();
-        return Promise.reject(error);
-      }
-      return operationResult.then(
-        (iteratorResult) => {
-          if (iteratorResult.done) settle();
-          return iteratorResult;
-        },
-        (error) => {
-          settle();
-          throw error;
-        },
-      );
-    };
-    const wrappedIterator: AsyncIterator<unknown, unknown, unknown> & AsyncIterable<unknown> = {
-      next: (...args: [] | [unknown]) => invoke(() => iterator.next(...args)),
-      return: iterator.return
-        ? async (...args: [] | [unknown]) => {
-            let iteratorResult = await invoke(() => iterator.return!(...args));
-            while (!iteratorResult.done) {
-              iteratorResult = await invoke(() => iterator.next());
-            }
-            return iteratorResult;
-          }
-        : async (...args: [] | [unknown]) => {
-            settle();
-            return { done: true, value: args[0] };
-          },
-      throw: iterator.throw
-        ? (error?: unknown) => invoke(() => iterator.throw!(error))
-        : async (error?: unknown) => {
-            settle();
-            throw error;
-          },
-      [Symbol.asyncIterator]() {
-        return this;
-      },
-    };
-    return wrappedIterator;
+  public static create(options: IAgentSessionOptions): Promise<AgentSession> {
+    return this.createWithFactory(options, () => new AgentSession(options));
   }
 }