@modelprofile.com/flexharness 1.0.0

package/ts/classes.flexharness.ts

@@ -0,0 +1,1648 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessCallbackOverflowError,
+  FlexHarnessClosedError,
+  FlexHarnessNotFoundError,
+  FlexHarnessPermissionRejectedError,
+  FlexHarnessPermissionStateError,
+  FlexHarnessRunError,
+  FlexHarnessSessionBusyError,
+  FlexHarnessValidationError,
+  errorMessage,
+  errorToInfo,
+} from './errors.js';
+import type {
+  IFlexAttachmentMessagePart,
+  IFlexCallbackLimits,
+  IFlexCreateSessionOptions,
+  IFlexHarnessOptions,
+  IFlexHarnessSnapshot,
+  IFlexMessage,
+  IFlexModelIdentity,
+  IFlexPartChangedEvent,
+  IFlexPermissionRequest,
+  IFlexPermissionRequestInput,
+  IFlexPromptOptions,
+  IFlexPromptResult,
+  IFlexResolvedModel,
+  IFlexResolvedScope,
+  IFlexRunFinishedEvent,
+  IFlexSession,
+  IFlexStoredSessionSnapshot,
+  IFlexToolHandle,
+  IFlexToolMessagePart,
+  IFlexUpdateSessionOptions,
+  IFlexUsage,
+  TFlexAgentModelMessage,
+  TFlexAgentRunResult,
+  TFlexAgentToolCallFinishEvent,
+  TFlexAgentToolSet,
+  TFlexAttachmentSource,
+  TFlexHarnessEvent,
+  TFlexHarnessEventListener,
+  TFlexMessagePart,
+  TFlexPermissionDecision,
+  TFlexPrompt,
+  TFlexPromptPart,
+} from './interfaces.js';
+import { InMemoryFlexHarnessStore } from './classes.stores.js';
+import {
+  assertFlexHarnessSnapshot,
+  cloneSerializable,
+  deepFreeze,
+  normalizeJsonValue,
+  resolveJsonLimits,
+  serializeAgentMessages,
+} from './utils.json.js';
+import {
+  hydrateAgentMessages,
+  normalizeFlexPrompt,
+  type INormalizedFlexPrompt,
+} from './utils.prompt.js';
+
+interface IStoredSessionState {
+  session: IFlexSession;
+  messages: IFlexMessage[];
+  modelHistory: TFlexAgentModelMessage[];
+  rememberedPermissionKeys: Set<string>;
+}
+
+interface IStorageState {
+  storageKey: string;
+  revision: number;
+  sessions: Map<string, IStoredSessionState>;
+  activeRuns: Map<string, IActiveRun>;
+  pendingPermissions: Map<string, IPendingPermission>;
+  saveTail: Promise<void>;
+}
+
+interface IActiveRun {
+  scopeId: string;
+  sessionId: string;
+  runId: string;
+  userMessageId: string;
+  assistantMessageId: string;
+  controller: AbortController;
+  ownerCancellation?: FlexHarnessAbortError;
+  internalFailure?: unknown;
+  finalizer: Promise<IFlexPromptResult>;
+  callbackError?: unknown;
+  callbackEventCount: number;
+  callbackOutputBytes: number;
+  callbackParts: TFlexMessagePart[];
+  callbacksClosed: boolean;
+  previousHistory: TFlexAgentModelMessage[];
+  reasoningPartIds: Map<string, string>;
+  toolPartIds: Map<string, string>;
+  pendingPermissionIds: Set<string>;
+  phase: 'resolving' | 'running' | 'closing' | 'committing';
+}
+
+interface IPendingPermission {
+  request: IFlexPermissionRequest;
+  run: IActiveRun;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+  settled: boolean;
+  responding: boolean;
+  abortReason?: unknown;
+  responseTail: Promise<void>;
+  abortListener: () => void;
+}
+
+interface IFinalMutationResult {
+  userMessage: IFlexMessage;
+  assistantMessage: IFlexMessage;
+  terminalParts: TFlexMessagePart[];
+}
+
+type TEventDetails = Record<string, unknown> & {
+  type: TFlexHarnessEvent['type'];
+};
+
+interface IExecutableToolRecord extends Record<string, unknown> {
+  execute?: (input: unknown, options: unknown) => unknown;
+}
+
+interface IResolverOutcome<T> {
+  source: 'model' | 'tools' | 'abort';
+  success: boolean;
+  value?: T;
+  error?: unknown;
+}
+
+const DEFAULT_CALLBACK_LIMITS: Required<IFlexCallbackLimits> = {
+  maxEvents: 10_000,
+  maxOutputBytes: 1024 * 1024,
+  maxParts: 2_000,
+};
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function',
+  );
+}
+
+async function* normalizeAsyncIterable(
+  iterable: AsyncIterable<unknown>,
+  limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+): AsyncGenerator<unknown> {
+  for await (const value of iterable) {
+    yield normalizeJsonValue(value, limits);
+  }
+}
+
+function wrapToolSet(
+  tools: TFlexAgentToolSet,
+  limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+): TFlexAgentToolSet {
+  const wrapped: Record<string, unknown> = {};
+  for (const [name, tool] of Object.entries(tools)) {
+    const toolRecord = tool as unknown as IExecutableToolRecord;
+    if (typeof toolRecord.execute !== 'function') {
+      wrapped[name] = tool;
+      continue;
+    }
+    const execute = toolRecord.execute;
+    wrapped[name] = {
+      ...toolRecord,
+      execute(input: unknown, options: unknown): unknown {
+        const output = execute.call(tool, input, options);
+        if (isAsyncIterable(output)) {
+          return normalizeAsyncIterable(output, limits);
+        }
+        return Promise.resolve(output).then((value) => normalizeJsonValue(value, limits));
+      },
+    };
+  }
+  return wrapped as TFlexAgentToolSet;
+}
+
+function publicSnapshot<T>(value: T): T {
+  return deepFreeze(cloneSerializable(value));
+}
+
+function validateIdentifier(value: string, name: string): void {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new FlexHarnessValidationError(`${name} must be a non-empty string.`);
+  }
+}
+
+function validateModelIdentity(identity: IFlexModelIdentity): void {
+  validateIdentifier(identity.provider, 'model identity provider');
+  validateIdentifier(identity.model, 'model identity model');
+  if (identity.displayName !== undefined) {
+    validateIdentifier(identity.displayName, 'model identity displayName');
+  }
+}
+
+function combineErrors(errors: unknown[]): unknown {
+  if (errors.length === 1) {
+    return errors[0];
+  }
+  return new FlexHarnessRunError(errors);
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    error instanceof FlexHarnessAbortError ||
+    (error instanceof DOMException && error.name === 'AbortError') ||
+    (error instanceof Error && error.name === 'AbortError')
+  );
+}
+
+function makeUsage(result: TFlexAgentRunResult): IFlexUsage {
+  return {
+    inputTokens: result.usage.inputTokens,
+    outputTokens: result.usage.outputTokens,
+    totalTokens: result.usage.totalTokens,
+    cacheReadTokens: result.usage.cacheReadTokens,
+    cacheWriteTokens: result.usage.cacheWriteTokens,
+  };
+}
+
+function base64Size(data: string): number | undefined {
+  const compact = data.replace(/\s/g, '');
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(compact) || compact.length % 4 === 1) {
+    return undefined;
+  }
+  return Buffer.from(compact, 'base64').byteLength;
+}
+
+function describeAttachment(
+  part: Exclude<TFlexPromptPart, { type: 'text' }>,
+): Omit<IFlexAttachmentMessagePart, 'partId' | 'type' | 'attachmentType'> {
+  let source: TFlexAttachmentSource = 'inline-base64';
+  let sizeBytes: number | undefined;
+  let inferredMediaType: string | undefined;
+
+  if (/^data:/i.test(part.data)) {
+    source = 'data-url';
+    const commaIndex = part.data.indexOf(',');
+    if (commaIndex >= 0) {
+      const metadata = part.data.slice(5, commaIndex);
+      const payload = part.data.slice(commaIndex + 1);
+      const metadataParts = metadata.split(';');
+      if (metadataParts[0]?.includes('/')) inferredMediaType = metadataParts[0];
+      if (metadataParts.some((entry) => entry.toLowerCase() === 'base64')) {
+        sizeBytes = base64Size(payload);
+      } else {
+        try {
+          sizeBytes = Buffer.byteLength(decodeURIComponent(payload));
+        } catch {
+          // Malformed URL encoding keeps size indeterminate without exposing the payload.
+        }
+      }
+    }
+  } else {
+    try {
+      const url = new URL(part.data);
+      if (url.protocol === 'http:' || url.protocol === 'https:') {
+        source = 'remote-url';
+      } else {
+        sizeBytes = base64Size(part.data);
+      }
+    } catch {
+      sizeBytes = base64Size(part.data);
+    }
+  }
+
+  return {
+    source,
+    ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+    ...(part.mediaType ?? inferredMediaType
+      ? { mediaType: part.mediaType ?? inferredMediaType }
+      : {}),
+    ...(part.name ? { name: part.name } : {}),
+  };
+}
+
+function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions): void {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new FlexHarnessValidationError('updateSession options must be a plain object.');
+  }
+  const keys = Object.keys(options);
+  if (keys.length === 0) {
+    throw new FlexHarnessValidationError('updateSession requires title or archived.');
+  }
+  const unsupportedKey = keys.find((key) => key !== 'title' && key !== 'archived');
+  if (unsupportedKey) {
+    throw new FlexHarnessValidationError(`updateSession does not support "${unsupportedKey}".`);
+  }
+  if (Object.prototype.hasOwnProperty.call(options, 'title')) {
+    if (options.title !== null) validateIdentifier(options.title!, 'title');
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(options, 'archived') &&
+    typeof options.archived !== 'boolean'
+  ) {
+    throw new FlexHarnessValidationError('archived must be a boolean.');
+  }
+}
+
+function resolveCallbackLimits(
+  limits: IFlexCallbackLimits = {},
+): Required<IFlexCallbackLimits> {
+  const resolved = {
+    maxEvents: limits.maxEvents ?? DEFAULT_CALLBACK_LIMITS.maxEvents,
+    maxOutputBytes: limits.maxOutputBytes ?? DEFAULT_CALLBACK_LIMITS.maxOutputBytes,
+    maxParts: limits.maxParts ?? DEFAULT_CALLBACK_LIMITS.maxParts,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new FlexHarnessValidationError(`callbackLimits.${name} must be a positive integer.`);
+    }
+  }
+  return resolved;
+}
+
+export class FlexHarness<TScope = unknown> {
+  private readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
+  private readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
+  private readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
+  private readonly store: NonNullable<IFlexHarnessOptions<TScope>['store']>;
+  private readonly runner: NonNullable<IFlexHarnessOptions<TScope>['runner']>;
+  private readonly toolOutputLimits: Required<
+    NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>
+  >;
+  private readonly callbackLimits: Required<IFlexCallbackLimits>;
+  private readonly stateLoads = new Map<string, Promise<IStorageState>>();
+  private readonly listeners = new Set<TFlexHarnessEventListener>();
+  private readonly detachedToolCleanups = new Set<Promise<void>>();
+  private sequence = 0;
+  private closed = false;
+  private disposePromise?: Promise<void>;
+
+  constructor(options: IFlexHarnessOptions<TScope>) {
+    this.scopeResolver = options.scopeResolver;
+    this.modelResolver = options.modelResolver;
+    this.toolProvider = options.toolProvider;
+    this.store = options.store ?? new InMemoryFlexHarnessStore();
+    this.runner = options.runner ?? plugins.runAgent;
+    this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
+    this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
+  }
+
+  public async listSessions(scopeId: string): Promise<IFlexSession[]> {
+    const { state } = await this.resolveState(scopeId);
+    await state.saveTail;
+    return publicSnapshot(
+      [...state.sessions.values()]
+        .map((entry) => entry.session)
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)),
+    );
+  }
+
+  public async createSession(
+    scopeId: string,
+    options: IFlexCreateSessionOptions = {},
+  ): Promise<IFlexSession> {
+    const { state } = await this.resolveState(scopeId);
+    const sessionId = options.sessionId ?? plugins.crypto.randomUUID();
+    validateIdentifier(sessionId, 'sessionId');
+    if (options.title !== undefined) {
+      validateIdentifier(options.title, 'title');
+    }
+    const session = await this.mutateAndSave(state, () => {
+      if (state.sessions.has(sessionId)) {
+        throw new FlexHarnessValidationError(`Session "${sessionId}" already exists.`);
+      }
+      const timestamp = new Date().toISOString();
+      const nextSession: IFlexSession = {
+        scopeId,
+        sessionId,
+        ...(options.title ? { title: options.title } : {}),
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        status: 'idle',
+        activity: { status: 'idle' },
+      };
+      state.sessions.set(sessionId, {
+        session: nextSession,
+        messages: [],
+        modelHistory: [],
+        rememberedPermissionKeys: new Set<string>(),
+      });
+      return publicSnapshot(nextSession);
+    });
+    this.emitEvent(scopeId, sessionId, {
+      type: 'session.created',
+      session,
+    });
+    return session;
+  }
+
+  public async getSession(scopeId: string, sessionId: string): Promise<IFlexSession> {
+    const { state } = await this.resolveState(scopeId);
+    await state.saveTail;
+    return publicSnapshot(this.requireSession(state, sessionId).session);
+  }
+
+  public async updateSession(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexUpdateSessionOptions,
+  ): Promise<IFlexSession> {
+    validateUpdateSessionOptions(options);
+    const { state } = await this.resolveState(scopeId);
+    const session = await this.mutateAndSave(state, () => {
+      const stored = this.requireMutableSession(state, sessionId);
+      const timestamp = new Date().toISOString();
+      if (Object.prototype.hasOwnProperty.call(options, 'title')) {
+        if (options.title === null) {
+          delete stored.session.title;
+        } else {
+          stored.session.title = options.title!;
+        }
+      }
+      if (options.archived === true) {
+        stored.session.archivedAt ??= timestamp;
+      } else if (options.archived === false) {
+        delete stored.session.archivedAt;
+      }
+      stored.session.updatedAt = timestamp;
+      return publicSnapshot(stored.session);
+    });
+    this.emitEvent(scopeId, sessionId, {
+      type: 'session.updated',
+      session,
+    });
+    return session;
+  }
+
+  public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
+    const { state } = await this.resolveState(scopeId);
+    const session = await this.mutateAndSave(state, () => {
+      const stored = this.requireMutableSession(state, sessionId);
+      const deletedSession = publicSnapshot(stored.session);
+      state.sessions.delete(sessionId);
+      return deletedSession;
+    });
+    this.emitEvent(scopeId, sessionId, {
+      type: 'session.deleted',
+      session,
+    });
+  }
+
+  public async getMessages(scopeId: string, sessionId: string): Promise<IFlexMessage[]> {
+    const { state } = await this.resolveState(scopeId);
+    await state.saveTail;
+    return publicSnapshot(this.requireSession(state, sessionId).messages);
+  }
+
+  public async prompt(
+    scopeId: string,
+    sessionId: string,
+    prompt: TFlexPrompt,
+    options: IFlexPromptOptions = {},
+  ): Promise<IFlexPromptResult> {
+    const normalizedPrompt = normalizeFlexPrompt(prompt);
+    if (options.maxSteps !== undefined && (!Number.isSafeInteger(options.maxSteps) || options.maxSteps < 1)) {
+      throw new FlexHarnessValidationError('maxSteps must be a positive integer.');
+    }
+    const resolved = await this.resolveState(scopeId);
+    await resolved.state.saveTail;
+    this.assertOpen();
+    this.requireSession(resolved.state, sessionId);
+    if (resolved.state.activeRuns.has(sessionId)) {
+      throw new FlexHarnessSessionBusyError(sessionId);
+    }
+
+    const run: IActiveRun = {
+      scopeId,
+      sessionId,
+      runId: plugins.crypto.randomUUID(),
+      userMessageId: plugins.crypto.randomUUID(),
+      assistantMessageId: plugins.crypto.randomUUID(),
+      controller: new AbortController(),
+      finalizer: Promise.reject(new Error('Run finalizer was not initialized.')),
+      callbackEventCount: 0,
+      callbackOutputBytes: 0,
+      callbackParts: [],
+      callbacksClosed: false,
+      previousHistory: [],
+      reasoningPartIds: new Map<string, string>(),
+      toolPartIds: new Map<string, string>(),
+      pendingPermissionIds: new Set<string>(),
+      phase: 'resolving',
+    };
+    void run.finalizer.catch(() => undefined);
+    resolved.state.activeRuns.set(sessionId, run);
+    run.finalizer = this.executeRun(resolved, run, normalizedPrompt, options);
+    return run.finalizer;
+  }
+
+  public async abort(scopeId: string, sessionId: string, reason?: string): Promise<boolean> {
+    const { state } = await this.resolveState(scopeId);
+    const run = state.activeRuns.get(sessionId);
+    if (!run || run.phase === 'committing') {
+      return false;
+    }
+    const error = new FlexHarnessAbortError(reason ?? 'The run was aborted by the caller.');
+    if (run.internalFailure === undefined) run.ownerCancellation ??= error;
+    this.rejectRunPermissions(state, run, error);
+    run.controller.abort(error);
+    return true;
+  }
+
+  public async listPendingPermissions(
+    scopeId: string,
+    sessionId?: string,
+  ): Promise<IFlexPermissionRequest[]> {
+    const { state } = await this.resolveState(scopeId);
+    await state.saveTail;
+    return publicSnapshot(
+      [...state.pendingPermissions.values()]
+        .map((pending) => pending.request)
+        .filter((request) => !sessionId || request.sessionId === sessionId)
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt)),
+    );
+  }
+
+  public async respondToPermission(
+    scopeId: string,
+    sessionId: string,
+    permissionId: string,
+    decision: TFlexPermissionDecision,
+  ): Promise<void> {
+    const { state } = await this.resolveState(scopeId);
+    const pending = state.pendingPermissions.get(permissionId);
+    if (!pending || pending.request.sessionId !== sessionId) {
+      throw new FlexHarnessNotFoundError('Permission', permissionId);
+    }
+    const response = pending.responseTail.then(() =>
+      this.applyPermissionResponse(state, pending, decision),
+    );
+    pending.responseTail = response.then(
+      () => undefined,
+      () => undefined,
+    );
+    return response;
+  }
+
+  public subscribe(listener: TFlexHarnessEventListener): () => void {
+    this.assertOpen();
+    this.listeners.add(listener);
+    let subscribed = true;
+    return () => {
+      if (!subscribed) return;
+      subscribed = false;
+      this.listeners.delete(listener);
+    };
+  }
+
+  public async dispose(): Promise<void> {
+    if (this.disposePromise) {
+      return this.disposePromise;
+    }
+    this.closed = true;
+    this.disposePromise = this.disposeInternal();
+    return this.disposePromise;
+  }
+
+  private async disposeInternal(): Promise<void> {
+    const states = (
+      await Promise.allSettled([...this.stateLoads.values()])
+    ).flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));
+    const finalizers: Promise<IFlexPromptResult>[] = [];
+    for (const state of states) {
+      for (const run of state.activeRuns.values()) {
+        finalizers.push(run.finalizer);
+        if (run.phase === 'committing') continue;
+        const error = new FlexHarnessAbortError('The run was aborted because FlexHarness was disposed.');
+        if (run.internalFailure === undefined) run.ownerCancellation ??= error;
+        this.rejectRunPermissions(state, run, error);
+        run.controller.abort(error);
+      }
+      for (const pending of [...state.pendingPermissions.values()]) {
+        this.rejectPending(
+          state,
+          pending,
+          new FlexHarnessAbortError('Permission was rejected because FlexHarness was disposed.'),
+        );
+      }
+    }
+    const results = await Promise.allSettled(finalizers);
+    await Promise.all(states.map((state) => state.saveTail));
+    const detachedCleanupResults = await Promise.allSettled([...this.detachedToolCleanups]);
+    this.listeners.clear();
+    this.stateLoads.clear();
+    this.detachedToolCleanups.clear();
+    for (const state of states) {
+      state.sessions.clear();
+      state.activeRuns.clear();
+      state.pendingPermissions.clear();
+    }
+    const unexpectedErrors: unknown[] = [];
+    for (const result of results) {
+      if (result.status === 'fulfilled') continue;
+      if (result.reason instanceof FlexHarnessRunError) {
+        for (const error of result.reason.errors) {
+          if (!isAbortError(error)) unexpectedErrors.push(error);
+        }
+      } else if (!isAbortError(result.reason)) {
+        unexpectedErrors.push(result.reason);
+      }
+    }
+    for (const result of detachedCleanupResults) {
+      if (result.status === 'rejected') unexpectedErrors.push(result.reason);
+    }
+    if (unexpectedErrors.length > 0) {
+      throw combineErrors(unexpectedErrors);
+    }
+  }
+
+  private async executeRun(
+    resolved: { scope: IFlexResolvedScope<TScope>; state: IStorageState },
+    run: IActiveRun,
+    prompt: INormalizedFlexPrompt,
+    options: IFlexPromptOptions,
+  ): Promise<IFlexPromptResult> {
+    let modelResolution: IFlexResolvedModel | undefined;
+    let toolHandle: IFlexToolHandle | undefined;
+    let result: TFlexAgentRunResult | undefined;
+    let serializedResultMessages: TFlexAgentModelMessage[] | undefined;
+    let originalError: unknown;
+    let reserved = false;
+
+    try {
+      const reservation = await this.reserveRun(resolved.state, run, prompt);
+      reserved = true;
+      this.emitEvent(run.scopeId, run.sessionId, {
+        type: 'run.started',
+        runId: run.runId,
+        messageId: run.userMessageId,
+        session: reservation.session,
+      });
+      this.emitEvent(run.scopeId, run.sessionId, {
+        type: 'message.created',
+        runId: run.runId,
+        messageId: run.userMessageId,
+        message: reservation.userMessage,
+      });
+      this.emitEvent(run.scopeId, run.sessionId, {
+        type: 'message.created',
+        runId: run.runId,
+        messageId: run.assistantMessageId,
+        message: reservation.assistantMessage,
+      });
+
+      const modelOutcome = Promise.resolve()
+        .then(() => this.modelResolver.resolveModel({
+          scopeId: run.scopeId,
+          scope: resolved.scope.scope,
+          sessionId: run.sessionId,
+          runId: run.runId,
+          ...(options.modelHint ? { modelHint: options.modelHint } : {}),
+          signal: run.controller.signal,
+        }))
+        .then(
+          (value): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: true, value }),
+          (error: unknown): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: false, error }),
+        );
+      const toolOutcome = Promise.resolve()
+        .then(() =>
+          this.toolProvider
+            ? this.toolProvider.provideTools({
+              scopeId: run.scopeId,
+              scope: resolved.scope.scope,
+              sessionId: run.sessionId,
+              runId: run.runId,
+              signal: run.controller.signal,
+              requestPermission: (request) =>
+                this.requestPermission(resolved.state, run, request),
+            })
+            : undefined,
+        )
+        .then(
+          (value): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: true, value }),
+          (error: unknown): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: false, error }),
+        );
+      let resolveAbort!: (outcome: IResolverOutcome<never>) => void;
+      const abortOutcome = new Promise<IResolverOutcome<never>>((resolve) => {
+        resolveAbort = resolve;
+      });
+      const onResolverAbort = () => {
+        resolveAbort({
+          source: 'abort',
+          success: false,
+          error: run.controller.signal.reason ?? new FlexHarnessAbortError(),
+        });
+      };
+      run.controller.signal.addEventListener('abort', onResolverAbort, { once: true });
+      if (run.controller.signal.aborted) onResolverAbort();
+
+      const firstResolver = await Promise.race([modelOutcome, toolOutcome, abortOutcome]);
+      if (!firstResolver.success) {
+        run.controller.signal.removeEventListener('abort', onResolverAbort);
+        if (firstResolver.source !== 'abort') {
+          this.abortRunInternally(run, firstResolver.error);
+        }
+        if (firstResolver.source !== 'tools') {
+          this.observeDetachedToolProvider(toolOutcome);
+        }
+        throw firstResolver.error;
+      }
+
+      if (firstResolver.source === 'model') {
+        modelResolution = firstResolver.value as IFlexResolvedModel;
+        try {
+          validateModelIdentity(modelResolution.identity);
+        } catch (error) {
+          run.controller.signal.removeEventListener('abort', onResolverAbort);
+          this.abortRunInternally(run, error);
+          this.observeDetachedToolProvider(toolOutcome);
+          throw error;
+        }
+      } else {
+        toolHandle = firstResolver.value as IFlexToolHandle | undefined;
+      }
+
+      const secondResolver = await Promise.race([
+        firstResolver.source === 'model' ? toolOutcome : modelOutcome,
+        abortOutcome,
+      ]);
+      run.controller.signal.removeEventListener('abort', onResolverAbort);
+      if (!secondResolver.success) {
+        if (secondResolver.source !== 'abort') {
+          this.abortRunInternally(run, secondResolver.error);
+        }
+        if (firstResolver.source === 'model' && secondResolver.source === 'abort') {
+          this.observeDetachedToolProvider(toolOutcome);
+        }
+        throw secondResolver.error;
+      }
+      if (secondResolver.source === 'model') {
+        modelResolution = secondResolver.value as IFlexResolvedModel;
+        try {
+          validateModelIdentity(modelResolution.identity);
+        } catch (error) {
+          this.abortRunInternally(run, error);
+          throw error;
+        }
+      } else {
+        toolHandle = secondResolver.value as IFlexToolHandle | undefined;
+      }
+      if (run.controller.signal.aborted) {
+        throw run.controller.signal.reason;
+      }
+
+      const runnerOptions: Parameters<typeof this.runner>[0] = {
+        model: modelResolution!.model,
+        prompt: prompt.agentPrompt,
+        messages: hydrateAgentMessages(run.previousHistory),
+        sessionId: run.sessionId,
+        abort: run.controller.signal,
+        ...(options.system ?? modelResolution!.system
+          ? { system: options.system ?? modelResolution!.system }
+          : {}),
+        ...(toolHandle ? { tools: wrapToolSet(toolHandle.tools, this.toolOutputLimits) } : {}),
+        ...(modelResolution!.providerOptions
+          ? { providerOptions: modelResolution!.providerOptions }
+          : {}),
+        ...(modelResolution!.cache !== undefined ? { cache: modelResolution!.cache } : {}),
+        ...(options.maxSteps ?? modelResolution!.maxSteps
+          ? { maxSteps: options.maxSteps ?? modelResolution!.maxSteps }
+          : {}),
+        onToken: (delta) => this.onTextDelta(run, delta),
+        onReasoningStart: (id) => this.onReasoningStart(run, id),
+        onReasoningDelta: (id, delta) => this.onReasoningDelta(run, id, delta),
+        onReasoningEnd: (id, text) => this.onReasoningEnd(run, id, text),
+        onToolCallStart: (event) => this.onToolStart(run, event),
+        onToolCallFinish: (event) => this.onToolFinish(run, event),
+      };
+      run.phase = 'running';
+      result = await this.runner(runnerOptions);
+      if (run.callbackError) {
+        throw run.callbackError;
+      }
+      if (run.controller.signal.aborted) {
+        throw run.controller.signal.reason;
+      }
+      serializedResultMessages = serializeAgentMessages(result.messages);
+    } catch (error) {
+      originalError = error ?? new Error('The run failed without an error value.');
+    }
+    run.callbacksClosed = true;
+    run.phase = 'closing';
+    if (run.callbackError && originalError !== run.callbackError) {
+      originalError = originalError === undefined
+        ? run.callbackError
+        : combineErrors([originalError, run.callbackError]);
+    }
+    if (originalError !== undefined && run.ownerCancellation === undefined) {
+      run.internalFailure ??= originalError;
+    }
+
+    if (!reserved) {
+      resolved.state.activeRuns.delete(run.sessionId);
+      throw originalError;
+    }
+
+    this.rejectRunPermissions(
+      resolved.state,
+      run,
+      originalError ??
+        run.ownerCancellation ??
+        new FlexHarnessAbortError('The run ended before permission was resolved.'),
+    );
+    const closeResult = await Promise.allSettled([
+      Promise.resolve().then(() => toolHandle?.close?.()),
+    ]).then(([settled]) => settled);
+    const errorsBeforePersistence: unknown[] = [];
+    if (originalError !== undefined) errorsBeforePersistence.push(originalError);
+    if (
+      originalError === undefined &&
+      run.ownerCancellation !== undefined
+    ) {
+      errorsBeforePersistence.push(run.ownerCancellation);
+    }
+    if (closeResult.status === 'rejected') {
+      errorsBeforePersistence.push(closeResult.reason);
+      run.internalFailure ??= closeResult.reason;
+    }
+    run.phase = 'committing';
+    if (
+      originalError === undefined &&
+      run.ownerCancellation !== undefined &&
+      !errorsBeforePersistence.includes(run.ownerCancellation)
+    ) {
+      errorsBeforePersistence.push(run.ownerCancellation);
+    }
+    const cancelled = run.ownerCancellation !== undefined && run.internalFailure === undefined;
+    const terminalError = errorsBeforePersistence.length > 0
+      ? combineErrors(errorsBeforePersistence)
+      : undefined;
+    const persistenceResult = await Promise.allSettled([this.finalizeRun(
+      resolved.state,
+      run,
+      prompt,
+      modelResolution,
+      result,
+      serializedResultMessages,
+      terminalError,
+      cancelled,
+    )]).then(([settled]) => settled);
+
+    if (persistenceResult.status === 'rejected') {
+      const allErrors = [...errorsBeforePersistence, persistenceResult.reason];
+      const combinedError = combineErrors(allErrors);
+      const fallback = this.applyRunFinalState(
+        resolved.state,
+        run,
+        prompt,
+        modelResolution,
+        result,
+        serializedResultMessages,
+        combinedError,
+        cancelled,
+      );
+      resolved.state.activeRuns.delete(run.sessionId);
+      this.emitFinalMutationEvents(run, fallback);
+      this.emitFinalRunEvent(run, fallback.assistantMessage, combinedError, cancelled);
+      throw combinedError;
+    }
+
+    const finalized = persistenceResult.value;
+    resolved.state.activeRuns.delete(run.sessionId);
+    this.emitFinalRunEvent(run, finalized.assistantMessage, terminalError, cancelled);
+    if (terminalError !== undefined) throw terminalError;
+    return {
+      runId: run.runId,
+      sessionId: run.sessionId,
+      userMessage: finalized.userMessage,
+      assistantMessage: finalized.assistantMessage,
+      model: publicSnapshot(modelResolution!.identity),
+      usage: publicSnapshot(makeUsage(result!)),
+      finishReason: result!.finishReason,
+      steps: result!.steps,
+    };
+  }
+
+  private async reserveRun(
+    state: IStorageState,
+    run: IActiveRun,
+    prompt: INormalizedFlexPrompt,
+  ): Promise<{ session: IFlexSession; userMessage: IFlexMessage; assistantMessage: IFlexMessage }> {
+    return this.mutateAndSave(state, () => {
+      const stored = this.requireSession(state, run.sessionId);
+      const timestamp = new Date().toISOString();
+      run.previousHistory = cloneSerializable(stored.modelHistory);
+      const userMessage: IFlexMessage = {
+        messageId: run.userMessageId,
+        sessionId: run.sessionId,
+        runId: run.runId,
+        role: 'user',
+        status: 'streaming',
+        createdAt: timestamp,
+        parts: prompt.parts.map((part) => {
+          if (part.type === 'text') {
+            return {
+              partId: plugins.crypto.randomUUID(),
+              type: 'text' as const,
+              text: part.text,
+            };
+          }
+          const attachment: IFlexAttachmentMessagePart = {
+            partId: plugins.crypto.randomUUID(),
+            type: 'attachment',
+            attachmentType: part.type,
+            ...describeAttachment(part),
+          };
+          return attachment;
+        }),
+      };
+      const assistantMessage: IFlexMessage = {
+        messageId: run.assistantMessageId,
+        sessionId: run.sessionId,
+        runId: run.runId,
+        role: 'assistant',
+        status: 'streaming',
+        createdAt: timestamp,
+        parts: [],
+      };
+      stored.messages.push(userMessage, assistantMessage);
+      stored.session.status = 'running';
+      stored.session.activity = {
+        runId: run.runId,
+        status: 'running',
+        startedAt: timestamp,
+      };
+      stored.session.updatedAt = timestamp;
+      return {
+        session: publicSnapshot(stored.session),
+        userMessage: publicSnapshot(userMessage),
+        assistantMessage: publicSnapshot(assistantMessage),
+      };
+    });
+  }
+
+  private async finalizeRun(
+    state: IStorageState,
+    run: IActiveRun,
+    prompt: INormalizedFlexPrompt,
+    model: IFlexResolvedModel | undefined,
+    result: TFlexAgentRunResult | undefined,
+    serializedResultMessages: TFlexAgentModelMessage[] | undefined,
+    originalError: unknown,
+    cancelled: boolean,
+  ): Promise<IFinalMutationResult> {
+    const final = await this.mutateAndSave(state, () =>
+      this.applyRunFinalState(
+        state,
+        run,
+        prompt,
+        model,
+        result,
+        serializedResultMessages,
+        originalError,
+        cancelled,
+      ),
+    );
+    this.emitFinalMutationEvents(run, final);
+    return final;
+  }
+
+  private applyRunFinalState(
+    state: IStorageState,
+    run: IActiveRun,
+    prompt: INormalizedFlexPrompt,
+    model: IFlexResolvedModel | undefined,
+    result: TFlexAgentRunResult | undefined,
+    serializedResultMessages: TFlexAgentModelMessage[] | undefined,
+    originalError: unknown,
+    cancelled: boolean,
+  ): IFinalMutationResult {
+    const stored = this.requireSession(state, run.sessionId);
+    const userMessage = this.requireMessage(stored, run.userMessageId);
+    const assistantMessage = this.requireMessage(stored, run.assistantMessageId);
+    assistantMessage.parts = cloneSerializable(run.callbackParts);
+    const timestamp = new Date().toISOString();
+    const terminalParts: TFlexMessagePart[] = [];
+    const success =
+      originalError === undefined &&
+      !cancelled &&
+      model !== undefined &&
+      result !== undefined &&
+      serializedResultMessages !== undefined;
+
+    for (const part of assistantMessage.parts) {
+      if (part.type === 'reasoning' && part.status === 'running') {
+        part.status = success ? 'completed' : 'cancelled';
+        terminalParts.push(publicSnapshot(part));
+      }
+      if (part.type === 'tool' && part.status === 'running') {
+        part.status = success ? 'failed' : cancelled ? 'cancelled' : 'failed';
+        part.error = success
+          ? 'Tool execution ended without a terminal event.'
+          : cancelled
+            ? 'Tool execution was cancelled.'
+            : errorMessage(originalError);
+        terminalParts.push(publicSnapshot(part));
+      }
+    }
+
+    if (success) {
+      if (!assistantMessage.parts.some((part) => part.type === 'text')) {
+        assistantMessage.parts.push({
+          partId: plugins.crypto.randomUUID(),
+          type: 'text',
+          text: result.text,
+        });
+      }
+      const usage = makeUsage(result);
+      userMessage.status = 'completed';
+      userMessage.completedAt = timestamp;
+      assistantMessage.status = 'completed';
+      assistantMessage.completedAt = timestamp;
+      assistantMessage.model = cloneSerializable(model.identity);
+      assistantMessage.usage = usage;
+      stored.modelHistory = [
+        ...run.previousHistory,
+        cloneSerializable(prompt.modelMessage),
+        ...serializedResultMessages,
+      ];
+      stored.session.status = 'idle';
+      stored.session.activity = {
+        runId: run.runId,
+        status: 'idle',
+        startedAt: stored.session.activity.startedAt,
+        completedAt: timestamp,
+      };
+    } else {
+      const status = cancelled ? 'cancelled' : 'failed';
+      const message = errorMessage(originalError);
+      userMessage.status = status;
+      userMessage.completedAt = timestamp;
+      userMessage.error = message;
+      assistantMessage.status = status;
+      assistantMessage.completedAt = timestamp;
+      assistantMessage.error = message;
+      if (model) assistantMessage.model = cloneSerializable(model.identity);
+      stored.session.status = status;
+      stored.session.activity = {
+        runId: run.runId,
+        status,
+        startedAt: stored.session.activity.startedAt,
+        completedAt: timestamp,
+        error: message,
+      };
+    }
+    stored.session.updatedAt = timestamp;
+    return {
+      userMessage: publicSnapshot(userMessage),
+      assistantMessage: publicSnapshot(assistantMessage),
+      terminalParts,
+    };
+  }
+
+  private emitFinalMutationEvents(run: IActiveRun, final: IFinalMutationResult): void {
+    for (const part of final.terminalParts) {
+      this.emitPartEvent(run, 'part.completed', part);
+    }
+    this.emitEvent(run.scopeId, run.sessionId, {
+      type: 'message.updated',
+      runId: run.runId,
+      messageId: run.userMessageId,
+      message: final.userMessage,
+    });
+    this.emitEvent(run.scopeId, run.sessionId, {
+      type: 'message.updated',
+      runId: run.runId,
+      messageId: run.assistantMessageId,
+      message: final.assistantMessage,
+    });
+  }
+
+  private emitFinalRunEvent(
+    run: IActiveRun,
+    message: IFlexMessage,
+    error: unknown,
+    cancelled: boolean,
+  ): void {
+    const status: IFlexRunFinishedEvent['status'] = error
+      ? cancelled
+        ? 'cancelled'
+        : 'failed'
+      : 'completed';
+    this.emitEvent(run.scopeId, run.sessionId, {
+      type: 'run.finished',
+      runId: run.runId,
+      messageId: run.assistantMessageId,
+      status,
+      message,
+      ...(error !== undefined ? { error: errorToInfo(error) } : {}),
+    });
+  }
+
+  private onTextDelta(run: IActiveRun, delta: string): void {
+    if (!delta || run.callbacksClosed || run.callbackError) return;
+    const lastPart = run.callbackParts.at(-1);
+    const created = lastPart?.type !== 'text';
+    const byteLength = Buffer.byteLength(delta);
+    if (!this.reserveCallbackCapacity(run, created ? 2 : 1, byteLength, created ? 1 : 0)) return;
+    const part = lastPart?.type === 'text'
+      ? lastPart
+      : { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: '' };
+    if (created) run.callbackParts.push(part);
+    part.text += delta;
+    if (created) this.emitPartEvent(run, 'part.started', part);
+    this.emitPartEvent(run, 'part.delta', part, delta);
+  }
+
+  private onReasoningStart(run: IActiveRun, id: string): void {
+    if (run.callbacksClosed || run.callbackError || run.reasoningPartIds.has(id)) return;
+    if (!this.reserveCallbackCapacity(run, 1, 0, 1)) return;
+    const part = {
+      partId: plugins.crypto.randomUUID(),
+      type: 'reasoning' as const,
+      text: '',
+      status: 'running' as const,
+    };
+    run.reasoningPartIds.set(id, part.partId);
+    run.callbackParts.push(part);
+    this.emitPartEvent(run, 'part.started', part);
+  }
+
+  private onReasoningDelta(run: IActiveRun, id: string, delta: string): void {
+    if (run.callbacksClosed || run.callbackError || !delta) return;
+    if (!run.reasoningPartIds.has(id)) this.onReasoningStart(run, id);
+    const partId = run.reasoningPartIds.get(id);
+    if (!partId || run.callbackError) return;
+    const part = run.callbackParts.find(
+      (entry) => entry.partId === partId && entry.type === 'reasoning',
+    );
+    if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
+    if (!this.reserveCallbackCapacity(run, 1, Buffer.byteLength(delta), 0)) return;
+    part.text += delta;
+    this.emitPartEvent(run, 'part.delta', part, delta);
+  }
+
+  private onReasoningEnd(run: IActiveRun, id: string, text: string): void {
+    if (run.callbacksClosed || run.callbackError) return;
+    if (!run.reasoningPartIds.has(id)) this.onReasoningStart(run, id);
+    const partId = run.reasoningPartIds.get(id);
+    if (!partId || run.callbackError) return;
+    const part = run.callbackParts.find(
+      (entry) => entry.partId === partId && entry.type === 'reasoning',
+    );
+    if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
+    const missingText = part.text.length === 0 ? text : '';
+    if (!this.reserveCallbackCapacity(run, 1, Buffer.byteLength(missingText), 0)) return;
+    if (missingText) part.text = missingText;
+    part.status = 'completed';
+    this.emitPartEvent(run, 'part.completed', part);
+  }
+
+  private onToolStart(
+    run: IActiveRun,
+    event: { toolCallId: string; toolName: string; input: unknown },
+  ): void {
+    if (run.callbacksClosed || run.callbackError || run.toolPartIds.has(event.toolCallId)) return;
+    const input = normalizeJsonValue(event.input, this.toolOutputLimits);
+    const byteLength = Buffer.byteLength(JSON.stringify(input));
+    if (!this.reserveCallbackCapacity(run, 1, byteLength, 1)) return;
+    const part: IFlexToolMessagePart = {
+      partId: plugins.crypto.randomUUID(),
+      type: 'tool',
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      status: 'running',
+      input,
+    };
+    run.toolPartIds.set(event.toolCallId, part.partId);
+    run.callbackParts.push(part);
+    this.emitPartEvent(run, 'part.started', part);
+  }
+
+  private onToolFinish(run: IActiveRun, event: TFlexAgentToolCallFinishEvent): void {
+    if (run.callbacksClosed || run.callbackError) return;
+    if (!run.toolPartIds.has(event.toolCallId)) this.onToolStart(run, event);
+    const partId = run.toolPartIds.get(event.toolCallId);
+    if (!partId || run.callbackError) return;
+    const part = run.callbackParts.find(
+      (entry) => entry.partId === partId && entry.type === 'tool',
+    );
+    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    const output = event.success
+      ? normalizeJsonValue(event.output, this.toolOutputLimits)
+      : undefined;
+    const byteLength = event.success
+      ? Buffer.byteLength(JSON.stringify(output))
+      : Buffer.byteLength(event.error);
+    if (!this.reserveCallbackCapacity(run, 1, byteLength, 0)) return;
+    if (event.success) {
+      part.status = 'completed';
+      part.output = output!;
+    } else {
+      part.status = 'failed';
+      part.error = event.error;
+    }
+    this.emitPartEvent(run, 'part.completed', part);
+  }
+
+  private reserveCallbackCapacity(
+    run: IActiveRun,
+    eventCount: number,
+    outputBytes: number,
+    partCount: number,
+  ): boolean {
+    const nextEvents = run.callbackEventCount + eventCount;
+    const nextOutputBytes = run.callbackOutputBytes + outputBytes;
+    const nextParts = run.callbackParts.length + partCount;
+    if (
+      nextEvents > this.callbackLimits.maxEvents ||
+      nextOutputBytes > this.callbackLimits.maxOutputBytes ||
+      nextParts > this.callbackLimits.maxParts
+    ) {
+      const error = new FlexHarnessCallbackOverflowError(
+        `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
+      );
+      run.callbackError = error;
+      this.abortRunInternally(run, error);
+      return false;
+    }
+    run.callbackEventCount = nextEvents;
+    run.callbackOutputBytes = nextOutputBytes;
+    return true;
+  }
+
+  private async requestPermission(
+    state: IStorageState,
+    run: IActiveRun,
+    input: IFlexPermissionRequestInput,
+  ): Promise<void> {
+    validateIdentifier(input.kind, 'permission kind');
+    validateIdentifier(input.description, 'permission description');
+    if (input.rememberKey !== undefined) validateIdentifier(input.rememberKey, 'rememberKey');
+    if (input.toolCallId !== undefined) validateIdentifier(input.toolCallId, 'toolCallId');
+    if (run.controller.signal.aborted) {
+      throw run.controller.signal.reason;
+    }
+    await state.saveTail;
+    if (run.controller.signal.aborted) {
+      throw run.controller.signal.reason;
+    }
+    if (
+      state.activeRuns.get(run.sessionId) !== run ||
+      run.callbacksClosed ||
+      run.phase === 'closing' ||
+      run.phase === 'committing'
+    ) {
+      throw new FlexHarnessPermissionStateError(
+        `Run "${run.runId}" no longer accepts permission requests.`,
+      );
+    }
+    const stored = this.requireSession(state, run.sessionId);
+    if (input.rememberKey && stored.rememberedPermissionKeys.has(input.rememberKey)) {
+      return;
+    }
+
+    const request: IFlexPermissionRequest = {
+      permissionId: plugins.crypto.randomUUID(),
+      scopeId: run.scopeId,
+      sessionId: run.sessionId,
+      runId: run.runId,
+      kind: input.kind,
+      description: input.description,
+      ...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
+      ...(input.rememberKey ? { rememberKey: input.rememberKey } : {}),
+      ...(input.metadata !== undefined ? { metadata: cloneSerializable(input.metadata) } : {}),
+      createdAt: new Date().toISOString(),
+    };
+    let resolvePermission!: () => void;
+    let rejectPermission!: (error: unknown) => void;
+    const permissionPromise = new Promise<void>((resolve, reject) => {
+      resolvePermission = resolve;
+      rejectPermission = reject;
+    });
+    void permissionPromise.catch(() => undefined);
+    const abortListener = () => {
+      const pending = state.pendingPermissions.get(request.permissionId);
+      if (pending) this.rejectPending(state, pending, run.controller.signal.reason);
+    };
+    const pending: IPendingPermission = {
+      request,
+      run,
+      resolve: resolvePermission,
+      reject: rejectPermission,
+      settled: false,
+      responding: false,
+      responseTail: Promise.resolve(),
+      abortListener,
+    };
+    state.pendingPermissions.set(request.permissionId, pending);
+    run.pendingPermissionIds.add(request.permissionId);
+    run.controller.signal.addEventListener('abort', abortListener, { once: true });
+    try {
+      await this.mutateAndSave(state, () => {
+        const current = this.requireSession(state, run.sessionId);
+        current.session.status = 'waiting_permission';
+        current.session.activity.status = 'waiting_permission';
+        current.session.updatedAt = new Date().toISOString();
+      });
+    } catch (error) {
+      state.pendingPermissions.delete(request.permissionId);
+      run.pendingPermissionIds.delete(request.permissionId);
+      run.controller.signal.removeEventListener('abort', abortListener);
+      throw error;
+    }
+    if (pending.settled) {
+      return permissionPromise;
+    }
+    this.emitEvent(run.scopeId, run.sessionId, {
+      type: 'permission.requested',
+      runId: run.runId,
+      request: publicSnapshot(request),
+    });
+    return permissionPromise;
+  }
+
+  private async applyPermissionResponse(
+    state: IStorageState,
+    pending: IPendingPermission,
+    decision: TFlexPermissionDecision,
+  ): Promise<void> {
+    if (pending.settled) {
+      throw new FlexHarnessPermissionStateError(
+        `Permission "${pending.request.permissionId}" has already been resolved.`,
+      );
+    }
+    if (!['once', 'always', 'reject'].includes(decision)) {
+      throw new FlexHarnessPermissionStateError(`Unknown permission decision "${decision}".`);
+    }
+    if (decision === 'always' && !pending.request.rememberKey) {
+      throw new FlexHarnessPermissionStateError(
+        'The always decision requires the permission request to provide rememberKey.',
+      );
+    }
+
+    const rememberKey = pending.request.rememberKey;
+    let addedRememberKey = false;
+    pending.responding = true;
+    try {
+      await this.mutateAndSave(state, () => {
+        const stored = this.requireSession(state, pending.request.sessionId);
+        if (decision === 'always' && rememberKey) {
+          addedRememberKey = !stored.rememberedPermissionKeys.has(rememberKey);
+          stored.rememberedPermissionKeys.add(rememberKey);
+        }
+        const hasOtherPending = [...state.pendingPermissions.values()].some(
+          (entry) =>
+            entry !== pending &&
+            !entry.settled &&
+            entry.request.sessionId === pending.request.sessionId,
+        );
+        stored.session.status = hasOtherPending ? 'waiting_permission' : 'running';
+        stored.session.activity.status = hasOtherPending ? 'waiting_permission' : 'running';
+        stored.session.updatedAt = new Date().toISOString();
+      });
+    } catch (error) {
+      pending.responding = false;
+      if (pending.abortReason !== undefined) {
+        const abortReason = pending.abortReason;
+        this.forceRejectPending(state, pending, abortReason);
+        throw combineErrors([abortReason, error]);
+      }
+      throw error;
+    }
+
+    if (pending.abortReason !== undefined) {
+      const abortReason = pending.abortReason;
+      const rollbackPromise = addedRememberKey && rememberKey
+        ? this.mutateAndSave(state, () => {
+            this.requireSession(
+              state,
+              pending.request.sessionId,
+            ).rememberedPermissionKeys.delete(rememberKey);
+          })
+        : Promise.resolve();
+      pending.responding = false;
+      this.forceRejectPending(state, pending, abortReason);
+      try {
+        await rollbackPromise;
+      } catch (rollbackError) {
+        throw combineErrors([abortReason, rollbackError]);
+      }
+      throw abortReason;
+    }
+
+    pending.settled = true;
+    pending.responding = false;
+    state.pendingPermissions.delete(pending.request.permissionId);
+    pending.run.pendingPermissionIds.delete(pending.request.permissionId);
+    pending.run.controller.signal.removeEventListener('abort', pending.abortListener);
+    this.emitEvent(pending.request.scopeId, pending.request.sessionId, {
+      type: 'permission.resolved',
+      runId: pending.request.runId,
+      request: publicSnapshot(pending.request),
+      decision,
+    });
+    if (decision === 'reject') {
+      pending.reject(new FlexHarnessPermissionRejectedError(pending.request.permissionId));
+    } else {
+      pending.resolve();
+    }
+  }
+
+  private rejectRunPermissions(state: IStorageState, run: IActiveRun, error: unknown): void {
+    for (const permissionId of [...run.pendingPermissionIds]) {
+      const pending = state.pendingPermissions.get(permissionId);
+      if (pending) this.rejectPending(state, pending, error);
+    }
+  }
+
+  private rejectPending(state: IStorageState, pending: IPendingPermission, error: unknown): void {
+    if (pending.settled) return;
+    if (pending.responding) {
+      pending.abortReason ??= error;
+      return;
+    }
+    this.forceRejectPending(state, pending, error);
+  }
+
+  private forceRejectPending(
+    state: IStorageState,
+    pending: IPendingPermission,
+    error: unknown,
+  ): void {
+    if (pending.settled) return;
+    pending.settled = true;
+    state.pendingPermissions.delete(pending.request.permissionId);
+    pending.run.pendingPermissionIds.delete(pending.request.permissionId);
+    pending.run.controller.signal.removeEventListener('abort', pending.abortListener);
+    pending.reject(error);
+  }
+
+  private emitPartEvent(
+    run: IActiveRun,
+    type: IFlexPartChangedEvent['type'],
+    part: TFlexMessagePart,
+    delta?: string,
+  ): void {
+    this.emitEvent(run.scopeId, run.sessionId, {
+      type,
+      runId: run.runId,
+      messageId: run.assistantMessageId,
+      partId: part.partId,
+      part: publicSnapshot(part),
+      ...(delta !== undefined ? { delta } : {}),
+    });
+  }
+
+  private abortRunInternally(run: IActiveRun, error: unknown): void {
+    run.internalFailure ??= error ?? new Error('Internal FlexHarness run failure.');
+    if (!run.controller.signal.aborted) {
+      run.controller.abort(run.internalFailure);
+    }
+  }
+
+  private observeDetachedToolProvider(
+    outcomePromise: Promise<IResolverOutcome<IFlexToolHandle | undefined>>,
+  ): void {
+    const cleanup = outcomePromise.then(async (outcome) => {
+      if (outcome.success && outcome.source === 'tools' && outcome.value?.close) {
+        await Promise.resolve().then(() => outcome.value!.close!());
+      }
+    });
+    this.detachedToolCleanups.add(cleanup);
+    void cleanup.then(
+      () => this.detachedToolCleanups.delete(cleanup),
+      () => undefined,
+    );
+  }
+
+  private emitEvent(scopeId: string, sessionId: string, details: TEventDetails): void {
+    const event = deepFreeze(
+      cloneSerializable({
+        eventId: plugins.crypto.randomUUID(),
+        sequence: ++this.sequence,
+        timestamp: new Date().toISOString(),
+        scopeId,
+        sessionId,
+        ...details,
+      }),
+    ) as TFlexHarnessEvent;
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Listener failures are isolated from the run and from other listeners.
+      }
+    }
+  }
+
+  private async resolveState(
+    scopeId: string,
+  ): Promise<{ scope: IFlexResolvedScope<TScope>; state: IStorageState }> {
+    this.assertOpen();
+    validateIdentifier(scopeId, 'scopeId');
+    const scope = await this.scopeResolver.resolveScope(scopeId);
+    this.assertOpen();
+    validateIdentifier(scope.storageKey, 'resolved storageKey');
+    let stateLoad = this.stateLoads.get(scope.storageKey);
+    if (!stateLoad) {
+      stateLoad = this.loadState(scope.storageKey);
+      this.stateLoads.set(scope.storageKey, stateLoad);
+      void stateLoad.catch(() => {
+        if (this.stateLoads.get(scope.storageKey) === stateLoad) {
+          this.stateLoads.delete(scope.storageKey);
+        }
+      });
+    }
+    const state = await stateLoad;
+    this.assertOpen();
+    return { scope, state };
+  }
+
+  private async loadState(storageKey: string): Promise<IStorageState> {
+    const loaded = await this.store.load(storageKey);
+    if (loaded) assertFlexHarnessSnapshot(loaded);
+    const snapshot = loaded ? cloneSerializable(loaded) : undefined;
+    const sessions = new Map<string, IStoredSessionState>();
+    const timestamp = new Date().toISOString();
+    for (const stored of snapshot?.sessions ?? []) {
+      if (stored.session.status === 'running' || stored.session.status === 'waiting_permission') {
+        stored.session.status = 'idle';
+        stored.session.activity = { status: 'idle' };
+        stored.session.updatedAt = timestamp;
+      }
+      for (const message of stored.messages) {
+        if (message.status === 'streaming') {
+          message.status = 'cancelled';
+          message.completedAt = timestamp;
+          message.error = 'The process stopped before this message completed.';
+        }
+        for (const part of message.parts) {
+          if (part.type === 'reasoning' && part.status === 'running') {
+            part.status = 'cancelled';
+          }
+          if (part.type === 'tool' && part.status === 'running') {
+            part.status = 'cancelled';
+            part.error = 'The process stopped before this tool call completed.';
+          }
+        }
+      }
+      sessions.set(stored.session.sessionId, {
+        session: stored.session,
+        messages: stored.messages,
+        modelHistory: stored.modelHistory as unknown as TFlexAgentModelMessage[],
+        rememberedPermissionKeys: new Set(stored.rememberedPermissionKeys),
+      });
+    }
+    return {
+      storageKey,
+      revision: snapshot?.revision ?? 0,
+      sessions,
+      activeRuns: new Map<string, IActiveRun>(),
+      pendingPermissions: new Map<string, IPendingPermission>(),
+      saveTail: Promise.resolve(),
+    };
+  }
+
+  private mutateAndSave<T>(state: IStorageState, mutation: () => T): Promise<T> {
+    const operation = state.saveTail.then(async () => {
+      const beforeMutation = this.createSnapshot(state, state.revision);
+      try {
+        const result = mutation();
+        const expectedRevision = state.revision;
+        const snapshot = this.createSnapshot(state, expectedRevision + 1);
+        assertFlexHarnessSnapshot(snapshot);
+        await this.store.save(state.storageKey, snapshot, expectedRevision);
+        state.revision = snapshot.revision;
+        return result;
+      } catch (error) {
+        this.restorePersistentState(state, beforeMutation);
+        throw error;
+      }
+    });
+    state.saveTail = operation.then(
+      () => undefined,
+      () => undefined,
+    );
+    return operation;
+  }
+
+  private restorePersistentState(state: IStorageState, snapshot: IFlexHarnessSnapshot): void {
+    state.revision = snapshot.revision;
+    state.sessions.clear();
+    for (const stored of snapshot.sessions) {
+      state.sessions.set(stored.session.sessionId, {
+        session: cloneSerializable(stored.session),
+        messages: cloneSerializable(stored.messages),
+        modelHistory: cloneSerializable(stored.modelHistory) as unknown as TFlexAgentModelMessage[],
+        rememberedPermissionKeys: new Set(stored.rememberedPermissionKeys),
+      });
+    }
+  }
+
+  private createSnapshot(state: IStorageState, revision: number): IFlexHarnessSnapshot {
+    const sessions: IFlexStoredSessionSnapshot[] = [...state.sessions.values()]
+      .sort((left, right) => left.session.sessionId.localeCompare(right.session.sessionId))
+      .map((stored) => ({
+        session: cloneSerializable(stored.session),
+        messages: cloneSerializable(stored.messages),
+        modelHistory: cloneSerializable(stored.modelHistory) as unknown as IFlexStoredSessionSnapshot['modelHistory'],
+        rememberedPermissionKeys: [...stored.rememberedPermissionKeys].sort(),
+      }));
+    return {
+      schemaVersion: 1,
+      revision,
+      sessions,
+    };
+  }
+
+  private requireSession(state: IStorageState, sessionId: string): IStoredSessionState {
+    validateIdentifier(sessionId, 'sessionId');
+    const session = state.sessions.get(sessionId);
+    if (!session) throw new FlexHarnessNotFoundError('Session', sessionId);
+    return session;
+  }
+
+  private requireMessage(stored: IStoredSessionState, messageId: string): IFlexMessage {
+    const message = stored.messages.find((entry) => entry.messageId === messageId);
+    if (!message) throw new FlexHarnessNotFoundError('Message', messageId);
+    return message;
+  }
+
+  private requireMutableSession(state: IStorageState, sessionId: string): IStoredSessionState {
+    const stored = this.requireSession(state, sessionId);
+    const hasPendingPermission = [...state.pendingPermissions.values()].some(
+      (pending) => !pending.settled && pending.request.sessionId === sessionId,
+    );
+    if (state.activeRuns.has(sessionId) || hasPendingPermission) {
+      throw new FlexHarnessSessionBusyError(
+        sessionId,
+        'cannot be changed while it has an active run or pending permission',
+      );
+    }
+    return stored;
+  }
+
+  private assertOpen(): void {
+    if (this.closed) throw new FlexHarnessClosedError();
+  }
+}