@modelprofile.com/flexharness 1.0.1 → 2.0.0

package/ts/classes.flexharness.ts

@@ -3,6 +3,7 @@ import {
   FlexHarnessAbortError,
   FlexHarnessCallbackOverflowError,
   FlexHarnessClosedError,
+  FlexHarnessExternalError,
   FlexHarnessNotFoundError,
   FlexHarnessPermissionRejectedError,
   FlexHarnessPermissionStateError,
@@ -16,14 +17,18 @@ import type {
   IFlexAttachmentMessagePart,
   IFlexCallbackLimits,
   IFlexCreateSessionOptions,
+  IFlexErrorInfo,
   IFlexHarnessOptions,
   IFlexHarnessSnapshot,
   IFlexMessage,
+  IFlexMessagePage,
+  IFlexMessagePageOptions,
   IFlexModelIdentity,
   IFlexPartChangedEvent,
   IFlexPermissionRequest,
   IFlexPermissionRequestInput,
   IFlexPromptOptions,
+  IFlexPromptAdmission,
   IFlexPromptResult,
   IFlexResolvedModel,
   IFlexResolvedScope,
@@ -39,6 +44,8 @@ import type {
   TFlexAgentToolCallFinishEvent,
   TFlexAgentToolSet,
   TFlexAttachmentSource,
+  TFlexExternalErrorProjector,
+  TFlexExternalErrorSource,
   TFlexHarnessEvent,
   TFlexHarnessEventListener,
   TFlexMessagePart,
@@ -84,6 +91,10 @@ interface IActiveRun {
   userMessageId: string;
   assistantMessageId: string;
   controller: AbortController;
+  admission: Promise<void>;
+  resolveAdmission: () => void;
+  rejectAdmission: (error: unknown) => void;
+  admissionSettled: boolean;
   ownerCancellation?: FlexHarnessAbortError;
   internalFailure?: unknown;
   finalizer: Promise<IFlexPromptResult>;
@@ -117,6 +128,13 @@ interface IFinalMutationResult {
   terminalParts: TFlexMessagePart[];
 }
 
+interface IRunResultProjection {
+  text: string;
+  steps: number;
+  finishReason: string;
+  usage: IFlexUsage;
+}
+
 type TEventDetails = Record<string, unknown> & {
   type: TFlexHarnessEvent['type'];
 };
@@ -132,11 +150,34 @@ interface IResolverOutcome<T> {
   error?: unknown;
 }
 
+interface IFlexMessageCursor {
+  version: 1;
+  namespace: string;
+  sessionId: string;
+  anchorMessageId: string;
+}
+
 const DEFAULT_CALLBACK_LIMITS: Required<IFlexCallbackLimits> = {
   maxEvents: 10_000,
   maxOutputBytes: 1024 * 1024,
   maxParts: 2_000,
 };
+const maxMessagePageSize = 50;
+const maxMessagePageCursorBytes = 4096;
+const maxTransferIdentifierBytes = 512;
+const maxTransferMetadataBytes = 2048;
+const maxTransferTextBytes = 96 * 1024;
+const maxTransferMessageBytes = 480 * 1024;
+const maxTransferPageBytes = 512 * 1024;
+const maxProjectedErrorNameBytes = 128;
+const maxProjectedErrorMessageBytes = 2048;
+const maxProjectedErrorCodeBytes = 128;
+const externalErrorFallback: IFlexErrorInfo = Object.freeze({
+  name: 'FlexHarnessExternalError',
+  message: 'The model operation failed.',
+  code: 'FLEX_EXTERNAL_ERROR',
+});
+const maxDetachedCleanupErrors = 100;
 
 function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
   return Boolean(
@@ -149,15 +190,21 @@ function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
 async function* normalizeAsyncIterable(
   iterable: AsyncIterable<unknown>,
   limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+  projectError: (error: unknown) => Error,
 ): AsyncGenerator<unknown> {
-  for await (const value of iterable) {
-    yield normalizeJsonValue(value, limits);
+  try {
+    for await (const value of iterable) {
+      yield normalizeJsonValue(value, limits);
+    }
+  } catch (error) {
+    throw projectError(error);
   }
 }
 
 function wrapToolSet(
   tools: TFlexAgentToolSet,
   limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+  projectError: (error: unknown) => Error,
 ): TFlexAgentToolSet {
   const wrapped: Record<string, unknown> = {};
   for (const [name, tool] of Object.entries(tools)) {
@@ -170,11 +217,31 @@ function wrapToolSet(
     wrapped[name] = {
       ...toolRecord,
       execute(input: unknown, options: unknown): unknown {
-        const output = execute.call(tool, input, options);
-        if (isAsyncIterable(output)) {
-          return normalizeAsyncIterable(output, limits);
+        let output: unknown;
+        try {
+          output = execute.call(tool, input, options);
+        } catch (error) {
+          throw projectError(error);
+        }
+        try {
+          if (isAsyncIterable(output)) {
+            return normalizeAsyncIterable(output, limits, projectError);
+          }
+        } catch (error) {
+          throw projectError(error);
         }
-        return Promise.resolve(output).then((value) => normalizeJsonValue(value, limits));
+        return Promise.resolve(output).then(
+          (value) => {
+            try {
+              return normalizeJsonValue(value, limits);
+            } catch (error) {
+              throw projectError(error);
+            }
+          },
+          (error: unknown) => {
+            throw projectError(error);
+          },
+        );
       },
     };
   }
@@ -185,25 +252,216 @@ function publicSnapshot<T>(value: T): T {
   return deepFreeze(cloneSerializable(value));
 }
 
+function jsonBytes(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, 'utf8') <= maxBytes) return value;
+  const suffix = ' [truncated]';
+  const suffixBytes = Buffer.byteLength(suffix, 'utf8');
+  let truncated = Buffer.from(value, 'utf8')
+    .subarray(0, Math.max(0, maxBytes - suffixBytes))
+    .toString('utf8')
+    .replace(/\uFFFD$/u, '');
+  while (Buffer.byteLength(`${truncated}${suffix}`, 'utf8') > maxBytes) {
+    truncated = truncated.slice(0, -1);
+  }
+  return `${truncated}${suffix}`;
+}
+
+function requireTransferIdentifier(value: string, field: string): void {
+  if (Buffer.byteLength(value, 'utf8') > maxTransferIdentifierBytes) {
+    throw new FlexHarnessValidationError(`Stored ${field} exceeds the transfer limit.`);
+  }
+}
+
+function createBoundedTransferMessage(message: IFlexMessage): IFlexMessage {
+  const projected = cloneSerializable(message);
+  requireTransferIdentifier(projected.messageId, 'messageId');
+  requireTransferIdentifier(projected.sessionId, 'sessionId');
+  requireTransferIdentifier(projected.runId, 'runId');
+  projected.createdAt = truncateUtf8(projected.createdAt, 128);
+  if (projected.completedAt !== undefined) {
+    projected.completedAt = truncateUtf8(projected.completedAt, 128);
+  }
+  if (projected.error !== undefined) {
+    projected.error = truncateUtf8(projected.error, maxTransferMetadataBytes);
+  }
+  if (projected.model) {
+    projected.model.provider = truncateUtf8(projected.model.provider, maxTransferIdentifierBytes);
+    projected.model.model = truncateUtf8(projected.model.model, maxTransferIdentifierBytes);
+    if (projected.model.displayName !== undefined) {
+      projected.model.displayName = truncateUtf8(
+        projected.model.displayName,
+        maxTransferMetadataBytes,
+      );
+    }
+    if (projected.model.variant !== undefined) {
+      projected.model.variant = truncateUtf8(projected.model.variant, 128);
+    }
+  }
+  for (const part of projected.parts) {
+    requireTransferIdentifier(part.partId, 'partId');
+    if (part.type === 'text' || part.type === 'reasoning') {
+      part.text = truncateUtf8(part.text, maxTransferTextBytes);
+    } else if (part.type === 'tool') {
+      part.toolCallId = truncateUtf8(part.toolCallId, maxTransferIdentifierBytes);
+      part.toolName = truncateUtf8(part.toolName, maxTransferIdentifierBytes);
+      if (part.error !== undefined) {
+        part.error = truncateUtf8(part.error, maxTransferMetadataBytes);
+      }
+    } else {
+      if (part.mediaType !== undefined) {
+        part.mediaType = truncateUtf8(part.mediaType, maxTransferIdentifierBytes);
+      }
+      if (part.name !== undefined) {
+        part.name = truncateUtf8(part.name, maxTransferMetadataBytes);
+      }
+    }
+  }
+  if (jsonBytes(projected) > maxTransferMessageBytes) {
+    projected.parts = [{
+      partId: 'transfer-elided',
+      type: 'text',
+      text: '[elided: message exceeds the transfer budget]',
+    }];
+  }
+  if (jsonBytes(projected) > maxTransferMessageBytes) {
+    throw new FlexHarnessValidationError('Stored message metadata exceeds the transfer limit.');
+  }
+  return projected;
+}
+
+function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessValidationError('External error projection is invalid.');
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const keys = Reflect.ownKeys(descriptors);
+  const unsupportedKey = keys.find(
+    (key) => typeof key !== 'string' || (key !== 'name' && key !== 'message' && key !== 'code'),
+  );
+  const name = descriptors.name?.value;
+  const message = descriptors.message?.value;
+  const code = descriptors.code?.value;
+  if (
+    unsupportedKey
+    || descriptors.name?.get !== undefined
+    || descriptors.name?.set !== undefined
+    || descriptors.message?.get !== undefined
+    || descriptors.message?.set !== undefined
+    || descriptors.code?.get !== undefined
+    || descriptors.code?.set !== undefined
+    || typeof name !== 'string'
+    || name.length === 0
+    || Buffer.byteLength(name, 'utf8') > maxProjectedErrorNameBytes
+    || typeof message !== 'string'
+    || message.length === 0
+    || Buffer.byteLength(message, 'utf8') > maxProjectedErrorMessageBytes
+    || (code !== undefined
+      && (
+        typeof code !== 'string'
+        || code.length === 0
+        || Buffer.byteLength(code, 'utf8') > maxProjectedErrorCodeBytes
+      ))
+  ) {
+    throw new FlexHarnessValidationError('External error projection is invalid.');
+  }
+  return Object.freeze({ name, message, ...(code === undefined ? {} : { code }) });
+}
+
 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 normalizeModelIdentity(identity: IFlexModelIdentity): IFlexModelIdentity {
+  const provider = identity.provider;
+  const model = identity.model;
+  const displayName = identity.displayName;
+  const variant = identity.variant;
+  const normalized: IFlexModelIdentity = {
+    provider,
+    model,
+    ...(displayName === undefined ? {} : { displayName }),
+    ...(variant === undefined ? {} : { variant }),
+  };
+  validateIdentifier(normalized.provider, 'model identity provider');
+  validateIdentifier(normalized.model, 'model identity model');
+  if (normalized.displayName !== undefined) {
+    validateIdentifier(normalized.displayName, 'model identity displayName');
+  }
+  if (normalized.variant !== undefined) {
+    validateIdentifier(normalized.variant, 'model identity variant');
+  }
+  if (
+    Buffer.byteLength(normalized.provider, 'utf8') > maxTransferIdentifierBytes
+    || Buffer.byteLength(normalized.model, 'utf8') > maxTransferIdentifierBytes
+    || (normalized.displayName !== undefined
+      && Buffer.byteLength(normalized.displayName, 'utf8') > maxTransferMetadataBytes)
+    || (normalized.variant !== undefined && Buffer.byteLength(normalized.variant, 'utf8') > 128)
+  ) {
+    throw new FlexHarnessValidationError('Model identity exceeds its transfer limit.');
   }
+  return normalized;
+}
+
+function normalizeResolvedModel(resolvedModel: IFlexResolvedModel): IFlexResolvedModel {
+  const model = resolvedModel.model;
+  const identity = normalizeModelIdentity(resolvedModel.identity);
+  const system = resolvedModel.system;
+  const providerOptions = resolvedModel.providerOptions;
+  const cache = resolvedModel.cache;
+  const maxSteps = resolvedModel.maxSteps;
+  return {
+    model,
+    identity,
+    ...(system === undefined ? {} : { system }),
+    ...(providerOptions === undefined ? {} : { providerOptions }),
+    ...(cache === undefined ? {} : { cache }),
+    ...(maxSteps === undefined ? {} : { maxSteps }),
+  };
+}
+
+function normalizeRunResult(result: TFlexAgentRunResult): IRunResultProjection {
+  const normalized: IRunResultProjection = {
+    text: result.text,
+    steps: result.steps,
+    finishReason: result.finishReason,
+    usage: {
+      inputTokens: result.usage.inputTokens,
+      outputTokens: result.usage.outputTokens,
+      totalTokens: result.usage.totalTokens,
+      cacheReadTokens: result.usage.cacheReadTokens,
+      cacheWriteTokens: result.usage.cacheWriteTokens,
+    },
+  };
+  if (
+    typeof normalized.text !== 'string'
+    || typeof normalized.finishReason !== 'string'
+    || !Number.isSafeInteger(normalized.steps)
+    || normalized.steps < 0
+    || Object.values(normalized.usage).some((value) => !Number.isFinite(value) || value < 0)
+  ) {
+    throw new FlexHarnessValidationError('Agent runner result is invalid.');
+  }
+  return normalized;
 }
 
 function combineErrors(errors: unknown[]): unknown {
   if (errors.length === 1) {
     return errors[0];
   }
-  return new FlexHarnessRunError(errors);
+  const combined = new FlexHarnessRunError(errors);
+  Object.freeze(combined.errors);
+  return Object.freeze(combined);
 }
 
 function isAbortError(error: unknown): boolean {
@@ -214,7 +472,7 @@ function isAbortError(error: unknown): boolean {
   );
 }
 
-function makeUsage(result: TFlexAgentRunResult): IFlexUsage {
+function makeUsage(result: IRunResultProjection): IFlexUsage {
   return {
     inputTokens: result.usage.inputTokens,
     outputTokens: result.usage.outputTokens,
@@ -329,9 +587,12 @@ export class FlexHarness<TScope = unknown> {
     NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>
   >;
   private readonly callbackLimits: Required<IFlexCallbackLimits>;
+  private readonly externalErrorProjector?: TFlexExternalErrorProjector;
   private readonly stateLoads = new Map<string, Promise<IStorageState>>();
   private readonly listeners = new Set<TFlexHarnessEventListener>();
   private readonly detachedToolCleanups = new Set<Promise<void>>();
+  private readonly detachedToolCleanupErrors: Error[] = [];
+  private readonly trustedInternalErrors = new WeakSet<object>();
   private sequence = 0;
   private closed = false;
   private disposePromise?: Promise<void>;
@@ -344,6 +605,7 @@ export class FlexHarness<TScope = unknown> {
     this.runner = options.runner ?? plugins.runAgent;
     this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
     this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
+    this.externalErrorProjector = options.externalErrorProjector;
   }
 
   public async listSessions(scopeId: string): Promise<IFlexSession[]> {
@@ -453,12 +715,122 @@ export class FlexHarness<TScope = unknown> {
     return publicSnapshot(this.requireSession(state, sessionId).messages);
   }
 
+  public async listMessagePage(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexMessagePageOptions = {},
+  ): Promise<IFlexMessagePage> {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new FlexHarnessValidationError('Message page options must be a plain object.');
+    }
+    const unsupportedKey = Object.keys(options).find(
+      (key) => key !== 'limit' && key !== 'before',
+    );
+    if (unsupportedKey) {
+      throw new FlexHarnessValidationError(
+        `Message page options do not support "${unsupportedKey}".`,
+      );
+    }
+    const limit = options.limit ?? maxMessagePageSize;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxMessagePageSize) {
+      throw new FlexHarnessValidationError(
+        `Message page limit must be an integer from 1 through ${maxMessagePageSize}.`,
+      );
+    }
+    if (
+      options.before !== undefined
+      && (
+        typeof options.before !== 'string'
+        || options.before.length === 0
+        || Buffer.byteLength(options.before, 'utf8') > maxMessagePageCursorBytes
+      )
+    ) {
+      throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    }
+    validateIdentifier(sessionId, 'sessionId');
+    requireTransferIdentifier(sessionId, 'sessionId');
+    const { state } = await this.resolveState(scopeId);
+    await state.saveTail;
+    const stored = this.requireSession(state, sessionId);
+    const namespace = this.messageCursorNamespace(state.storageKey);
+    let end = stored.messages.length;
+    if (options.before !== undefined) {
+      const cursor = this.parseMessageCursor(options.before);
+      if (cursor.namespace !== namespace || cursor.sessionId !== sessionId) {
+        throw new FlexHarnessValidationError('Message page cursor is invalid.');
+      }
+      const anchorIndex = stored.messages.findIndex(
+        (message) => message.messageId === cursor.anchorMessageId,
+      );
+      if (anchorIndex < 0) {
+        throw new FlexHarnessValidationError('Message page cursor is stale.');
+      }
+      end = anchorIndex;
+    }
+
+    let start = end;
+    let messages: IFlexMessage[] = [];
+    for (let index = end - 1; index >= 0 && messages.length < limit; index--) {
+      const candidate = createBoundedTransferMessage(stored.messages[index]);
+      const candidateMessages = [candidate, ...messages];
+      const nextCursor = index > 0
+        ? this.createMessageCursor(namespace, sessionId, candidate.messageId)
+        : undefined;
+      const candidatePage: IFlexMessagePage = {
+        messages: candidateMessages,
+        ...(nextCursor === undefined ? {} : { nextCursor }),
+      };
+      if (jsonBytes(candidatePage) > maxTransferPageBytes) break;
+      start = index;
+      messages = candidateMessages;
+    }
+    if (messages.length === 0 && end > 0) {
+      throw new FlexHarnessValidationError('Stored message exceeds the page transfer limit.');
+    }
+    const nextCursor = start > 0
+      ? this.createMessageCursor(namespace, sessionId, messages[0].messageId)
+      : undefined;
+    const page: IFlexMessagePage = {
+      messages,
+      ...(nextCursor === undefined ? {} : { nextCursor }),
+    };
+    if (jsonBytes(page) > maxTransferPageBytes) {
+      throw new FlexHarnessValidationError('Message page exceeds the transfer limit.');
+    }
+    return publicSnapshot(page);
+  }
+
+  public async getMessage(
+    scopeId: string,
+    sessionId: string,
+    messageId: string,
+  ): Promise<IFlexMessage> {
+    validateIdentifier(sessionId, 'sessionId');
+    requireTransferIdentifier(sessionId, 'sessionId');
+    validateIdentifier(messageId, 'messageId');
+    requireTransferIdentifier(messageId, 'messageId');
+    const { state } = await this.resolveState(scopeId);
+    await state.saveTail;
+    const message = this.requireMessage(this.requireSession(state, sessionId), messageId);
+    return publicSnapshot(createBoundedTransferMessage(message));
+  }
+
   public async prompt(
     scopeId: string,
     sessionId: string,
     prompt: TFlexPrompt,
     options: IFlexPromptOptions = {},
   ): Promise<IFlexPromptResult> {
+    const admission = await this.startPrompt(scopeId, sessionId, prompt, options);
+    return admission.completion;
+  }
+
+  public async startPrompt(
+    scopeId: string,
+    sessionId: string,
+    prompt: TFlexPrompt,
+    options: IFlexPromptOptions = {},
+  ): Promise<IFlexPromptAdmission> {
     const normalizedPrompt = normalizeFlexPrompt(prompt);
     if (options.maxSteps !== undefined && (!Number.isSafeInteger(options.maxSteps) || options.maxSteps < 1)) {
       throw new FlexHarnessValidationError('maxSteps must be a positive integer.');
@@ -471,6 +843,19 @@ export class FlexHarness<TScope = unknown> {
       throw new FlexHarnessSessionBusyError(sessionId);
     }
 
+    let resolveAdmission!: () => void;
+    let rejectAdmission!: (error: unknown) => void;
+    const admission = new Promise<void>((resolve, reject) => {
+      resolveAdmission = resolve;
+      rejectAdmission = reject;
+    });
+    void admission.catch(() => undefined);
+    let resolveCompletion!: (result: IFlexPromptResult) => void;
+    let rejectCompletion!: (error: unknown) => void;
+    const completion = new Promise<IFlexPromptResult>((resolve, reject) => {
+      resolveCompletion = resolve;
+      rejectCompletion = reject;
+    });
     const run: IActiveRun = {
       scopeId,
       sessionId,
@@ -478,7 +863,11 @@ export class FlexHarness<TScope = unknown> {
       userMessageId: plugins.crypto.randomUUID(),
       assistantMessageId: plugins.crypto.randomUUID(),
       controller: new AbortController(),
-      finalizer: Promise.reject(new Error('Run finalizer was not initialized.')),
+      admission,
+      resolveAdmission,
+      rejectAdmission,
+      admissionSettled: false,
+      finalizer: completion,
       callbackEventCount: 0,
       callbackOutputBytes: 0,
       callbackParts: [],
@@ -491,17 +880,21 @@ export class FlexHarness<TScope = unknown> {
     };
     void run.finalizer.catch(() => undefined);
     resolved.state.activeRuns.set(sessionId, run);
-    run.finalizer = this.executeRun(resolved, run, normalizedPrompt, options);
-    return run.finalizer;
+    void this.executeRun(resolved, run, normalizedPrompt, options).then(
+      resolveCompletion,
+      rejectCompletion,
+    );
+    await run.admission;
+    return Object.freeze({ runId: run.runId, completion: run.finalizer });
   }
 
-  public async abort(scopeId: string, sessionId: string, reason?: string): Promise<boolean> {
+  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.');
+    const error = Object.freeze(new FlexHarnessAbortError());
     if (run.internalFailure === undefined) run.ownerCancellation ??= error;
     this.rejectRunPermissions(state, run, error);
     run.controller.abort(error);
@@ -572,7 +965,9 @@ export class FlexHarness<TScope = unknown> {
       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.');
+        const error = Object.freeze(
+          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);
@@ -581,13 +976,15 @@ export class FlexHarness<TScope = unknown> {
         this.rejectPending(
           state,
           pending,
-          new FlexHarnessAbortError('Permission was rejected because FlexHarness was disposed.'),
+          Object.freeze(
+            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]);
+    await Promise.all([...this.detachedToolCleanups]);
     this.listeners.clear();
     this.stateLoads.clear();
     this.detachedToolCleanups.clear();
@@ -607,9 +1004,8 @@ export class FlexHarness<TScope = unknown> {
         unexpectedErrors.push(result.reason);
       }
     }
-    for (const result of detachedCleanupResults) {
-      if (result.status === 'rejected') unexpectedErrors.push(result.reason);
-    }
+    unexpectedErrors.push(...this.detachedToolCleanupErrors);
+    this.detachedToolCleanupErrors.length = 0;
     if (unexpectedErrors.length > 0) {
       throw combineErrors(unexpectedErrors);
     }
@@ -623,7 +1019,7 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<IFlexPromptResult> {
     let modelResolution: IFlexResolvedModel | undefined;
     let toolHandle: IFlexToolHandle | undefined;
-    let result: TFlexAgentRunResult | undefined;
+    let result: IRunResultProjection | undefined;
     let serializedResultMessages: TFlexAgentModelMessage[] | undefined;
     let originalError: unknown;
     let reserved = false;
@@ -649,6 +1045,7 @@ export class FlexHarness<TScope = unknown> {
         messageId: run.assistantMessageId,
         message: reservation.assistantMessage,
       });
+      this.resolveRunAdmission(run);
 
       const modelOutcome = Promise.resolve()
         .then(() => this.modelResolver.resolveModel({
@@ -660,8 +1057,16 @@ export class FlexHarness<TScope = unknown> {
           signal: run.controller.signal,
         }))
         .then(
-          (value): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: true, value }),
-          (error: unknown): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: false, error }),
+          (value): IResolverOutcome<IFlexResolvedModel> => ({
+            source: 'model',
+            success: true,
+            value,
+          }),
+          (error: unknown): IResolverOutcome<IFlexResolvedModel> => ({
+            source: 'model',
+            success: false,
+            error,
+          }),
         );
       const toolOutcome = Promise.resolve()
         .then(() =>
@@ -678,8 +1083,16 @@ export class FlexHarness<TScope = unknown> {
             : undefined,
         )
         .then(
-          (value): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: true, value }),
-          (error: unknown): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: false, error }),
+          (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) => {
@@ -698,27 +1111,41 @@ export class FlexHarness<TScope = unknown> {
       const firstResolver = await Promise.race([modelOutcome, toolOutcome, abortOutcome]);
       if (!firstResolver.success) {
         run.controller.signal.removeEventListener('abort', onResolverAbort);
+        const firstError = firstResolver.source === 'abort'
+          ? firstResolver.error
+          : this.projectExternalError(
+              run,
+              firstResolver.error,
+              firstResolver.source === 'model' ? 'modelResolver' : 'toolProvider',
+            );
         if (firstResolver.source !== 'abort') {
-          this.abortRunInternally(run, firstResolver.error);
+          this.abortRunInternally(run, firstError);
         }
         if (firstResolver.source !== 'tools') {
-          this.observeDetachedToolProvider(toolOutcome);
+          this.observeDetachedToolProvider(toolOutcome, run);
         }
-        throw firstResolver.error;
+        throw firstError;
       }
 
-      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;
+      try {
+        if (firstResolver.source === 'model') {
+          modelResolution = normalizeResolvedModel(firstResolver.value as IFlexResolvedModel);
+        } else {
+          toolHandle = this.normalizeToolHandle(
+            run,
+            firstResolver.value as IFlexToolHandle | undefined,
+          );
         }
-      } else {
-        toolHandle = firstResolver.value as IFlexToolHandle | undefined;
+      } catch (error) {
+        const resolverError = firstResolver.source === 'model'
+          ? this.projectExternalError(run, error, 'modelResolver')
+          : error;
+        run.controller.signal.removeEventListener('abort', onResolverAbort);
+        this.abortRunInternally(run, resolverError);
+        if (firstResolver.source === 'model') {
+          this.observeDetachedToolProvider(toolOutcome, run);
+        }
+        throw resolverError;
       }
 
       const secondResolver = await Promise.race([
@@ -727,29 +1154,53 @@ export class FlexHarness<TScope = unknown> {
       ]);
       run.controller.signal.removeEventListener('abort', onResolverAbort);
       if (!secondResolver.success) {
+        const secondError = secondResolver.source === 'abort'
+          ? secondResolver.error
+          : this.projectExternalError(
+              run,
+              secondResolver.error,
+              secondResolver.source === 'model' ? 'modelResolver' : 'toolProvider',
+            );
         if (secondResolver.source !== 'abort') {
-          this.abortRunInternally(run, secondResolver.error);
+          this.abortRunInternally(run, secondError);
         }
         if (firstResolver.source === 'model' && secondResolver.source === 'abort') {
-          this.observeDetachedToolProvider(toolOutcome);
+          this.observeDetachedToolProvider(toolOutcome, run);
         }
-        throw secondResolver.error;
+        throw secondError;
       }
-      if (secondResolver.source === 'model') {
-        modelResolution = secondResolver.value as IFlexResolvedModel;
-        try {
-          validateModelIdentity(modelResolution.identity);
-        } catch (error) {
-          this.abortRunInternally(run, error);
-          throw error;
+      try {
+        if (secondResolver.source === 'model') {
+          modelResolution = normalizeResolvedModel(secondResolver.value as IFlexResolvedModel);
+        } else {
+          toolHandle = this.normalizeToolHandle(
+            run,
+            secondResolver.value as IFlexToolHandle | undefined,
+          );
         }
-      } else {
-        toolHandle = secondResolver.value as IFlexToolHandle | undefined;
+      } catch (error) {
+        const resolverError = secondResolver.source === 'model'
+          ? this.projectExternalError(run, error, 'modelResolver')
+          : error;
+        this.abortRunInternally(run, resolverError);
+        throw resolverError;
       }
       if (run.controller.signal.aborted) {
         throw run.controller.signal.reason;
       }
 
+      let tools: TFlexAgentToolSet | undefined;
+      try {
+        tools = toolHandle
+          ? wrapToolSet(
+              toolHandle.tools,
+              this.toolOutputLimits,
+              (error) => this.projectExternalError(run, error, 'toolExecution'),
+            )
+          : undefined;
+      } catch (error) {
+        throw this.projectExternalError(run, error, 'toolProvider');
+      }
       const runnerOptions: Parameters<typeof this.runner>[0] = {
         model: modelResolution!.model,
         prompt: prompt.agentPrompt,
@@ -759,7 +1210,7 @@ export class FlexHarness<TScope = unknown> {
         ...(options.system ?? modelResolution!.system
           ? { system: options.system ?? modelResolution!.system }
           : {}),
-        ...(toolHandle ? { tools: wrapToolSet(toolHandle.tools, this.toolOutputLimits) } : {}),
+        ...(tools ? { tools } : {}),
         ...(modelResolution!.providerOptions
           ? { providerOptions: modelResolution!.providerOptions }
           : {}),
@@ -775,16 +1226,22 @@ export class FlexHarness<TScope = unknown> {
         onToolCallFinish: (event) => this.onToolFinish(run, event),
       };
       run.phase = 'running';
-      result = await this.runner(runnerOptions);
+      try {
+        const runnerResult = await this.runner(runnerOptions);
+        serializedResultMessages = serializeAgentMessages(runnerResult.messages);
+        result = normalizeRunResult(runnerResult);
+      } catch (error) {
+        throw this.projectExternalError(run, error, 'runner');
+      }
       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.');
+      const runError = error ?? new Error('The run failed without an error value.');
+      originalError = reserved ? this.projectExternalError(run, runError, 'runner') : runError;
     }
     run.callbacksClosed = true;
     run.phase = 'closing';
@@ -793,15 +1250,18 @@ export class FlexHarness<TScope = unknown> {
         ? run.callbackError
         : combineErrors([originalError, run.callbackError]);
     }
+    if (!reserved) {
+      const admissionError = this.projectExternalError(run, originalError, 'persistence');
+      this.rejectRunAdmission(run, admissionError);
+      if (resolved.state.activeRuns.get(run.sessionId) === run) {
+        resolved.state.activeRuns.delete(run.sessionId);
+      }
+      throw admissionError;
+    }
     if (originalError !== undefined && run.ownerCancellation === undefined) {
       run.internalFailure ??= originalError;
     }
 
-    if (!reserved) {
-      resolved.state.activeRuns.delete(run.sessionId);
-      throw originalError;
-    }
-
     this.rejectRunPermissions(
       resolved.state,
       run,
@@ -810,7 +1270,11 @@ export class FlexHarness<TScope = unknown> {
         new FlexHarnessAbortError('The run ended before permission was resolved.'),
     );
     const closeResult = await Promise.allSettled([
-      Promise.resolve().then(() => toolHandle?.close?.()),
+      Promise.resolve()
+        .then(() => toolHandle?.close?.())
+        .catch((error) => {
+          throw this.projectExternalError(run, error, 'toolCleanup');
+        }),
     ]).then(([settled]) => settled);
     const errorsBeforePersistence: unknown[] = [];
     if (originalError !== undefined) errorsBeforePersistence.push(originalError);
@@ -848,7 +1312,12 @@ export class FlexHarness<TScope = unknown> {
     )]).then(([settled]) => settled);
 
     if (persistenceResult.status === 'rejected') {
-      const allErrors = [...errorsBeforePersistence, persistenceResult.reason];
+      const persistenceError = this.projectExternalError(
+        run,
+        persistenceResult.reason,
+        'persistence',
+      );
+      const allErrors = [...errorsBeforePersistence, persistenceError];
       const combinedError = combineErrors(allErrors);
       const fallback = this.applyRunFinalState(
         resolved.state,
@@ -860,14 +1329,18 @@ export class FlexHarness<TScope = unknown> {
         combinedError,
         cancelled,
       );
-      resolved.state.activeRuns.delete(run.sessionId);
+      if (resolved.state.activeRuns.get(run.sessionId) === run) {
+        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);
+    if (resolved.state.activeRuns.get(run.sessionId) === run) {
+      resolved.state.activeRuns.delete(run.sessionId);
+    }
     this.emitFinalRunEvent(run, finalized.assistantMessage, terminalError, cancelled);
     if (terminalError !== undefined) throw terminalError;
     return {
@@ -945,7 +1418,7 @@ export class FlexHarness<TScope = unknown> {
     run: IActiveRun,
     prompt: INormalizedFlexPrompt,
     model: IFlexResolvedModel | undefined,
-    result: TFlexAgentRunResult | undefined,
+    result: IRunResultProjection | undefined,
     serializedResultMessages: TFlexAgentModelMessage[] | undefined,
     originalError: unknown,
     cancelled: boolean,
@@ -971,7 +1444,7 @@ export class FlexHarness<TScope = unknown> {
     run: IActiveRun,
     prompt: INormalizedFlexPrompt,
     model: IFlexResolvedModel | undefined,
-    result: TFlexAgentRunResult | undefined,
+    result: IRunResultProjection | undefined,
     serializedResultMessages: TFlexAgentModelMessage[] | undefined,
     originalError: unknown,
     cancelled: boolean,
@@ -1190,16 +1663,19 @@ export class FlexHarness<TScope = unknown> {
     const output = event.success
       ? normalizeJsonValue(event.output, this.toolOutputLimits)
       : undefined;
+    const projectedError = event.success
+      ? undefined
+      : this.projectExternalError(run, event.error, 'toolCallback');
     const byteLength = event.success
       ? Buffer.byteLength(JSON.stringify(output))
-      : Buffer.byteLength(event.error);
+      : Buffer.byteLength(projectedError!.message);
     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;
+      part.error = projectedError!.message;
     }
     this.emitPartEvent(run, 'part.completed', part);
   }
@@ -1218,8 +1694,10 @@ export class FlexHarness<TScope = unknown> {
       nextOutputBytes > this.callbackLimits.maxOutputBytes ||
       nextParts > this.callbackLimits.maxParts
     ) {
-      const error = new FlexHarnessCallbackOverflowError(
-        `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
+      const error = Object.freeze(
+        new FlexHarnessCallbackOverflowError(
+          `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
+        ),
       );
       run.callbackError = error;
       this.abortRunInternally(run, error);
@@ -1308,7 +1786,7 @@ export class FlexHarness<TScope = unknown> {
       state.pendingPermissions.delete(request.permissionId);
       run.pendingPermissionIds.delete(request.permissionId);
       run.controller.signal.removeEventListener('abort', abortListener);
-      throw error;
+      throw this.projectExternalError(run, error, 'persistence');
     }
     if (pending.settled) {
       return permissionPromise;
@@ -1361,13 +1839,14 @@ export class FlexHarness<TScope = unknown> {
         stored.session.updatedAt = new Date().toISOString();
       });
     } catch (error) {
+      const persistenceError = this.projectExternalError(pending.run, error, 'persistence');
       pending.responding = false;
       if (pending.abortReason !== undefined) {
         const abortReason = pending.abortReason;
         this.forceRejectPending(state, pending, abortReason);
-        throw combineErrors([abortReason, error]);
+        throw combineErrors([abortReason, persistenceError]);
       }
-      throw error;
+      throw persistenceError;
     }
 
     if (pending.abortReason !== undefined) {
@@ -1381,12 +1860,21 @@ export class FlexHarness<TScope = unknown> {
           })
         : Promise.resolve();
       pending.responding = false;
-      this.forceRejectPending(state, pending, abortReason);
       try {
         await rollbackPromise;
       } catch (rollbackError) {
-        throw combineErrors([abortReason, rollbackError]);
+        if (addedRememberKey && rememberKey) {
+          state.sessions
+            .get(pending.request.sessionId)
+            ?.rememberedPermissionKeys.delete(rememberKey);
+        }
+        this.forceRejectPending(state, pending, abortReason);
+        throw combineErrors([
+          abortReason,
+          this.projectExternalError(pending.run, rollbackError, 'persistence'),
+        ]);
       }
+      this.forceRejectPending(state, pending, abortReason);
       throw abortReason;
     }
 
@@ -1402,7 +1890,10 @@ export class FlexHarness<TScope = unknown> {
       decision,
     });
     if (decision === 'reject') {
-      pending.reject(new FlexHarnessPermissionRejectedError(pending.request.permissionId));
+      const error = this.trustInternalError(
+        new FlexHarnessPermissionRejectedError(pending.request.permissionId),
+      );
+      pending.reject(error);
     } else {
       pending.resolve();
     }
@@ -1460,19 +1951,102 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private projectExternalError(
+    run: IActiveRun,
+    error: unknown,
+    source: TFlexExternalErrorSource,
+  ): Error {
+    if ((typeof error === 'object' && error !== null) || typeof error === 'function') {
+      if (
+        error === run.ownerCancellation
+        || error === run.callbackError
+        || this.trustedInternalErrors.has(error)
+      ) {
+        return error as Error;
+      }
+    }
+    let info = externalErrorFallback;
+    if (this.externalErrorProjector) {
+      try {
+        info = validateProjectedErrorInfo(this.externalErrorProjector(error, {
+          source,
+          scopeId: run.scopeId,
+          sessionId: run.sessionId,
+          runId: run.runId,
+        }));
+      } catch {
+        info = externalErrorFallback;
+      }
+    }
+    return this.trustInternalError(new FlexHarnessExternalError(info));
+  }
+
+  private trustInternalError<TError extends Error>(error: TError): TError {
+    Object.freeze(error);
+    this.trustedInternalErrors.add(error);
+    return error;
+  }
+
+  private normalizeToolHandle(
+    run: IActiveRun,
+    toolHandle: IFlexToolHandle | undefined,
+  ): IFlexToolHandle | undefined {
+    if (toolHandle === undefined) return undefined;
+    let close: IFlexToolHandle['close'];
+    try {
+      close = toolHandle.close;
+      if (close !== undefined && typeof close !== 'function') {
+        throw new FlexHarnessValidationError('Tool handle close must be a function.');
+      }
+    } catch (error) {
+      throw this.projectExternalError(run, error, 'toolProvider');
+    }
+    const closeHandle = close === undefined ? undefined : () => close.call(toolHandle);
+    try {
+      const tools = toolHandle.tools;
+      return {
+        tools,
+        ...(closeHandle === undefined ? {} : { close: closeHandle }),
+      };
+    } catch (error) {
+      if (closeHandle) this.trackDetachedToolCleanup(closeHandle, run);
+      throw this.projectExternalError(run, error, 'toolProvider');
+    }
+  }
+
+  private trackDetachedToolCleanup(
+    cleanup: () => Promise<void> | void,
+    run: IActiveRun,
+  ): void {
+    let tracked!: Promise<void>;
+    tracked = Promise.resolve()
+      .then(cleanup)
+      .catch((error) => {
+        if (this.detachedToolCleanupErrors.length < maxDetachedCleanupErrors) {
+          this.detachedToolCleanupErrors.push(
+            this.projectExternalError(run, error, 'toolCleanup'),
+          );
+        }
+      })
+      .finally(() => {
+        this.detachedToolCleanups.delete(tracked);
+      });
+    this.detachedToolCleanups.add(tracked);
+  }
+
   private observeDetachedToolProvider(
     outcomePromise: Promise<IResolverOutcome<IFlexToolHandle | undefined>>,
+    run: IActiveRun,
   ): void {
-    const cleanup = outcomePromise.then(async (outcome) => {
-      if (outcome.success && outcome.source === 'tools' && outcome.value?.close) {
-        await Promise.resolve().then(() => outcome.value!.close!());
+    this.trackDetachedToolCleanup(async () => {
+      const outcome = await outcomePromise;
+      if (!outcome.success || outcome.source !== 'tools' || !outcome.value) return;
+      const close = outcome.value.close;
+      if (close !== undefined && typeof close !== 'function') {
+        throw new FlexHarnessValidationError('Tool handle close must be a function.');
       }
-    });
-    this.detachedToolCleanups.add(cleanup);
-    void cleanup.then(
-      () => this.detachedToolCleanups.delete(cleanup),
-      () => undefined,
-    );
+      await close?.call(outcome.value);
+    }, run);
   }
 
   private emitEvent(scopeId: string, sessionId: string, details: TEventDetails): void {
@@ -1615,6 +2189,76 @@ export class FlexHarness<TScope = unknown> {
     };
   }
 
+  private messageCursorNamespace(storageKey: string): string {
+    return plugins.crypto.createHash('sha256').update(storageKey).digest('base64url');
+  }
+
+  private createMessageCursor(
+    namespace: string,
+    sessionId: string,
+    anchorMessageId: string,
+  ): string {
+    const cursor = Buffer.from(JSON.stringify({
+      version: 1,
+      namespace,
+      sessionId,
+      anchorMessageId,
+    } satisfies IFlexMessageCursor)).toString('base64url');
+    if (Buffer.byteLength(cursor, 'utf8') > maxMessagePageCursorBytes) {
+      throw new FlexHarnessValidationError('Message page cursor exceeds its transfer limit.');
+    }
+    return cursor;
+  }
+
+  private parseMessageCursor(cursor: string): IFlexMessageCursor {
+    let parsed: unknown;
+    try {
+      const decoded = Buffer.from(cursor, 'base64url');
+      if (decoded.toString('base64url') !== cursor) {
+        throw new Error('non-canonical cursor');
+      }
+      parsed = JSON.parse(decoded.toString('utf8'));
+    } catch {
+      throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    }
+    if (
+      !parsed
+      || typeof parsed !== 'object'
+      || Array.isArray(parsed)
+      || Object.keys(parsed).length !== 4
+      || (parsed as Partial<IFlexMessageCursor>).version !== 1
+      || typeof (parsed as Partial<IFlexMessageCursor>).namespace !== 'string'
+      || typeof (parsed as Partial<IFlexMessageCursor>).sessionId !== 'string'
+      || typeof (parsed as Partial<IFlexMessageCursor>).anchorMessageId !== 'string'
+    ) {
+      throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    }
+    const result = parsed as IFlexMessageCursor;
+    if (
+      result.namespace.length === 0
+      || result.sessionId.length === 0
+      || result.anchorMessageId.length === 0
+      || Buffer.byteLength(result.namespace, 'utf8') > 128
+      || Buffer.byteLength(result.sessionId, 'utf8') > maxTransferIdentifierBytes
+      || Buffer.byteLength(result.anchorMessageId, 'utf8') > maxTransferIdentifierBytes
+    ) {
+      throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    }
+    return result;
+  }
+
+  private resolveRunAdmission(run: IActiveRun): void {
+    if (run.admissionSettled) return;
+    run.admissionSettled = true;
+    run.resolveAdmission();
+  }
+
+  private rejectRunAdmission(run: IActiveRun, error: unknown): void {
+    if (run.admissionSettled) return;
+    run.admissionSettled = true;
+    run.rejectAdmission(error);
+  }
+
   private requireSession(state: IStorageState, sessionId: string): IStoredSessionState {
     validateIdentifier(sessionId, 'sessionId');
     const session = state.sessions.get(sessionId);