@modelprofile.com/flexharness 3.1.0 → 3.2.0

package/ts/classes.flexharness.ts

@@ -7,6 +7,7 @@ import {
   FlexHarnessNotFoundError,
   FlexHarnessPermissionRejectedError,
   FlexHarnessPermissionStateError,
+  FlexHarnessQueueFullError,
   FlexHarnessRunError,
   FlexHarnessSessionBusyError,
   FlexHarnessStoreConflictError,
@@ -34,6 +35,9 @@ import type {
   IFlexPermissionRequestInput,
   IFlexPermissionSnapshot,
   IFlexPromptAdmission,
+  IFlexPromptQueueAdmission,
+  IFlexPromptQueueEntry,
+  IFlexPromptQueueLimits,
   IFlexPromptOptions,
   IFlexPromptResult,
   IFlexProjectionSnapshot,
@@ -64,6 +68,7 @@ import type {
   TFlexPermissionDecision,
   TFlexPrompt,
   TFlexPromptPart,
+  TFlexPromptQueueStatus,
   TFlexToolExecutionReconciliation,
 } from './interfaces.js';
 import { InMemoryFlexHarnessStores } from './classes.stores.js';
@@ -108,6 +113,11 @@ interface IStoredSessionState {
   executionContextCloseCompleted: boolean;
   jobStoreReleased: boolean;
   jobs?: NonNullable<plugins.IToolExecutionContext['jobs']>;
+  promptQueue: IQueuedPrompt[];
+  outstandingPromptsById: Map<string, IQueuedPrompt>;
+  terminalPromptQueueEntries: Map<string, IFlexPromptQueueEntry>;
+  outstandingPromptBytes: number;
+  promptQueueDrain?: Promise<void>;
 }
 
 interface IRetainedSessionCleanup {
@@ -160,6 +170,7 @@ interface IActiveRun {
   scopeId: string;
   scope: unknown;
   sessionId: string;
+  queueId: string;
   runId: string;
   userMessageId: string;
   assistantMessageId: string;
@@ -182,8 +193,37 @@ interface IActiveRun {
   reservedAssistantMessage?: IFlexMessage;
   modelResolution?: IFlexResolvedModel;
   completion: Promise<IFlexPromptResult>;
+}
+
+interface IQueuedPrompt {
+  state: IStorageState;
+  stored: IStoredSessionState;
+  scopeId: string;
+  scope: unknown;
+  sessionId: string;
+  queueId: string;
+  queueSequence: number;
+  status: Exclude<TFlexPromptQueueStatus, 'completed' | 'failed' | 'cancelled'>;
+  queuedAt: string;
+  runId?: string;
+  scheduleKey?: string;
+  debounceMs?: number;
+  startedAt?: string;
+  prompt?: INormalizedFlexPrompt;
+  options?: IFlexPromptOptions;
+  byteSize: number;
+  completion: Promise<IFlexPromptResult>;
   resolveCompletion: (result: IFlexPromptResult) => void;
   rejectCompletion: (error: unknown) => void;
+  started: Promise<IFlexPromptAdmission>;
+  resolveStarted: (admission: IFlexPromptAdmission) => void;
+  rejectStarted: (error: unknown) => void;
+}
+
+interface IPendingPromptAdmission {
+  controller: AbortController;
+  settled: Promise<void>;
+  resolveSettled: () => void;
 }
 
 interface IPendingPermission {
@@ -238,6 +278,13 @@ const DEFAULT_CALLBACK_LIMITS: Required<IFlexCallbackLimits> = {
   maxOutputBytes: 1024 * 1024,
   maxParts: 2_000,
 };
+const DEFAULT_PROMPT_QUEUE_LIMITS: Required<IFlexPromptQueueLimits> = {
+  maxOutstandingPromptsPerSession: 16,
+  maxOutstandingBytesPerSession: 64 * 1024 * 1024,
+  maxPendingAdmissions: 64,
+  maxPendingAdmissionBytes: 128 * 1024 * 1024,
+  maxTerminalEntriesPerSession: 64,
+};
 const maxMessagePageSize = 50;
 const maxMessagePageCursorBytes = 4096;
 const maxTransferIdentifierBytes = 512;
@@ -624,6 +671,29 @@ function resolveCallbackLimits(limits: IFlexCallbackLimits = {}): Required<IFlex
   return resolved;
 }
 
+function resolvePromptQueueLimits(
+  limits: IFlexPromptQueueLimits = {},
+): Required<IFlexPromptQueueLimits> {
+  const resolved = {
+    maxOutstandingPromptsPerSession: limits.maxOutstandingPromptsPerSession
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxOutstandingPromptsPerSession,
+    maxOutstandingBytesPerSession: limits.maxOutstandingBytesPerSession
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxOutstandingBytesPerSession,
+    maxPendingAdmissions: limits.maxPendingAdmissions
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxPendingAdmissions,
+    maxPendingAdmissionBytes: limits.maxPendingAdmissionBytes
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxPendingAdmissionBytes,
+    maxTerminalEntriesPerSession: limits.maxTerminalEntriesPerSession
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxTerminalEntriesPerSession,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new FlexHarnessValidationError(`promptQueueLimits.${name} must be a positive integer.`);
+    }
+  }
+  return resolved;
+}
+
 function normalizeAgentSessionPolicy(policy: IFlexAgentSessionPolicy = {}): IFlexAgentSessionPolicy {
   return {
     ...(policy.contextBuilder === undefined ? {} : { contextBuilder: policy.contextBuilder }),
@@ -656,6 +726,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly agentSessionPolicy: IFlexAgentSessionPolicy;
   private readonly toolOutputLimits: Required<NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>>;
   private readonly callbackLimits: Required<IFlexCallbackLimits>;
+  private readonly promptQueueLimits: Required<IFlexPromptQueueLimits>;
   private readonly externalErrorProjector?: TFlexExternalErrorProjector;
   private readonly stateLoads = new Map<string, Promise<IStorageState>>();
   private readonly scopeAdmissions = new Map<string, IScopeAdmissionState>();
@@ -670,7 +741,11 @@ export class FlexHarness<TScope = unknown> {
     IOrphanedExecutionContextOwner
   >();
   private readonly orphanedProviderReleases = new Map<string, IOrphanedProviderRelease>();
+  private readonly pendingPromptAdmissionOwners = new Set<IPendingPromptAdmission>();
   private sequence = 0;
+  private promptQueueSequence = 0;
+  private pendingPromptAdmissions = 0;
+  private pendingPromptAdmissionBytes = 0;
   private closed = false;
   private disposePromise?: Promise<void>;
 
@@ -686,6 +761,7 @@ export class FlexHarness<TScope = unknown> {
     this.agentSessionPolicy = normalizeAgentSessionPolicy(options.agentSessionPolicy);
     this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
     this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
+    this.promptQueueLimits = resolvePromptQueueLimits(options.promptQueueLimits);
     this.externalErrorProjector = options.externalErrorProjector;
   }
 
@@ -1021,7 +1097,19 @@ export class FlexHarness<TScope = unknown> {
     options: IFlexPromptOptions = {},
   ): Promise<IFlexPromptAdmission> {
     validatePromptOptions(options, false);
-    return this.admitPrompt(scopeId, sessionId, normalizeFlexPrompt(prompt), options);
+    const queued = await this.enqueuePromptInternal(scopeId, sessionId, prompt, options);
+    return queued.started;
+  }
+
+  public async enqueuePrompt(
+    scopeId: string,
+    sessionId: string,
+    prompt: TFlexPrompt,
+    options: IFlexPromptOptions = {},
+  ): Promise<IFlexPromptQueueAdmission> {
+    validatePromptOptions(options, false);
+    const queued = await this.enqueuePromptInternal(scopeId, sessionId, prompt, options);
+    return queued.admission;
   }
 
   public async schedulePrompt(
@@ -1040,17 +1128,66 @@ export class FlexHarness<TScope = unknown> {
         `debounceMs must be an integer from 0 through ${maxScheduleDebounceMs}.`,
       );
     }
-    const admission = await this.admitPrompt(
+    const queued = await this.enqueuePromptInternal(
       scopeId,
       sessionId,
-      normalizeFlexPrompt(prompt),
+      prompt,
       options,
       scheduleKey,
       debounceMs,
     );
+    const admission = await queued.started;
     return Object.freeze({ ...admission, scheduleKey });
   }
 
+  public async getPromptQueueEntry(
+    scopeId: string,
+    sessionId: string,
+    queueId: string,
+  ): Promise<IFlexPromptQueueEntry> {
+    validateIdentifier(queueId, 'queueId');
+    requireTransferIdentifier(queueId, 'queueId');
+    const { state } = await this.resolveState(scopeId);
+    this.assertStateAcceptingWork(state);
+    const stored = this.requireSession(state, sessionId);
+    const entry = this.promptQueueEntry(stored, queueId);
+    if (!entry) throw new FlexHarnessNotFoundError('Prompt queue entry', queueId);
+    return publicSnapshot(entry);
+  }
+
+  public async listPromptQueueEntries(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexPromptQueueEntry[]> {
+    const { state } = await this.resolveState(scopeId);
+    this.assertStateAcceptingWork(state);
+    const stored = this.requireSession(state, sessionId);
+    return publicSnapshot([
+      ...[...stored.outstandingPromptsById.values()].map((entry) => this.projectPromptQueueEntry(entry)),
+      ...stored.terminalPromptQueueEntries.values(),
+    ].sort((left, right) => left.queueSequence - right.queueSequence));
+  }
+
+  public async cancelPrompt(
+    scopeId: string,
+    sessionId: string,
+    queueId: string,
+  ): Promise<boolean> {
+    validateIdentifier(queueId, 'queueId');
+    requireTransferIdentifier(queueId, 'queueId');
+    const { state } = await this.resolveState(scopeId);
+    const stored = this.requireSession(state, sessionId);
+    const queued = stored.outstandingPromptsById.get(queueId);
+    if (!queued) {
+      if (stored.terminalPromptQueueEntries.has(queueId)) return false;
+      throw new FlexHarnessNotFoundError('Prompt queue entry', queueId);
+    }
+    return this.cancelQueuedPrompt(
+      queued,
+      this.trustInternalError(new FlexHarnessAbortError('The queued prompt was cancelled.')),
+    );
+  }
+
   public async cancelScheduledPrompt(
     scopeId: string,
     sessionId: string,
@@ -1058,18 +1195,12 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<boolean> {
     validateIdentifier(scheduleKey, 'scheduleKey');
     const { state } = await this.resolveState(scopeId);
-    const run = state.activeRuns.get(sessionId);
-    if (!run || run.scheduleKey !== scheduleKey || run.phase === 'finalizing' || run.phase === 'promoting') {
-      return false;
-    }
+    const stored = this.requireSession(state, sessionId);
+    const queued = [...stored.outstandingPromptsById.values()]
+      .find((entry) => entry.scheduleKey === scheduleKey);
+    if (!queued) return false;
     const cancellation = this.trustInternalError(new FlexHarnessAbortError('The scheduled run was cancelled.'));
-    if (run.internalFailure === undefined) run.ownerCancellation ??= cancellation;
-    this.rejectRunPermissions(state, run, cancellation);
-    if (!run.controller.signal.aborted) run.controller.abort(cancellation);
-    run.stored.agentSession.cancelScheduledGeneration(scheduleKey, cancellation);
-    const settled = await Promise.allSettled([run.completion]);
-    if (settled[0].status === 'rejected' && !isAbortError(settled[0].reason)) throw settled[0].reason;
-    return true;
+    return this.cancelQueuedPrompt(queued, cancellation);
   }
 
   public async abort(scopeId: string, sessionId: string): Promise<boolean> {
@@ -1321,45 +1452,199 @@ export class FlexHarness<TScope = unknown> {
     return disposal;
   }
 
-  private async admitPrompt(
+  private async enqueuePromptInternal(
     scopeId: string,
     sessionId: string,
-    prompt: INormalizedFlexPrompt,
+    prompt: TFlexPrompt,
     options: IFlexPromptOptions,
     scheduleKey?: string,
     debounceMs?: number,
-  ): Promise<IFlexPromptAdmission> {
-    const resolved = await this.resolveState(scopeId);
-    const state = resolved.state;
-    await state.scopeQueue;
-    this.assertStateAcceptingWork(state);
-    const stored = this.requireSession(state, sessionId);
-    await stored.projectionQueue;
-    if (state.activeRuns.has(sessionId)) {
-      const active = state.activeRuns.get(sessionId)!;
-      const reason = scheduleKey && active.scheduleKey === scheduleKey
-        ? `already has scheduled key "${scheduleKey}"`
-        : 'already has an active run';
-      throw new FlexHarnessSessionBusyError(sessionId, reason);
-    }
-    let resolveCompletion!: (result: IFlexPromptResult) => void;
-    let rejectCompletion!: (error: unknown) => void;
-    const completion = new Promise<IFlexPromptResult>((resolve, reject) => {
-      resolveCompletion = resolve;
-      rejectCompletion = reject;
+  ): Promise<{ admission: IFlexPromptQueueAdmission; started: Promise<IFlexPromptAdmission> }> {
+    this.assertOpen();
+    const normalizedPrompt = normalizeFlexPrompt(prompt);
+    const normalizedOptions = cloneSerializable(options);
+    const byteSize = jsonBytes({
+      prompt: normalizedPrompt,
+      options: normalizedOptions,
+      scheduleKey,
+      debounceMs,
     });
-    void completion.catch(() => undefined);
-    const run: IActiveRun = {
-      state,
-      stored,
-      scopeId,
-      scope: resolved.scope.scope,
-      sessionId,
-      runId: plugins.crypto.randomUUID(),
+    const releasePendingAdmission = this.reservePendingPromptAdmission(byteSize);
+    let resolveSettled!: () => void;
+    const pendingOwner: IPendingPromptAdmission = {
+      controller: new AbortController(),
+      settled: new Promise<void>((resolve) => {
+        resolveSettled = resolve;
+      }),
+      resolveSettled: () => resolveSettled(),
+    };
+    this.pendingPromptAdmissionOwners.add(pendingOwner);
+    let abortAdmission!: () => void;
+    const abortPromise = new Promise<never>((_resolve, reject) => {
+      abortAdmission = () => reject(
+        pendingOwner.controller.signal.reason ?? new FlexHarnessAbortError(),
+      );
+      pendingOwner.controller.signal.addEventListener('abort', abortAdmission, { once: true });
+      if (pendingOwner.controller.signal.aborted) abortAdmission();
+    });
+    try {
+      const resolved = await Promise.race([this.resolveState(scopeId), abortPromise]);
+      const state = resolved.state;
+      await Promise.race([state.scopeQueue, abortPromise]);
+      this.assertStateAcceptingWork(state);
+      const stored = this.requireSession(state, sessionId);
+      if (stored.outstandingPromptsById.size >= this.promptQueueLimits.maxOutstandingPromptsPerSession) {
+        throw new FlexHarnessQueueFullError(
+          `Session "${sessionId}" has reached its outstanding prompt limit.`,
+        );
+      }
+      if (
+        stored.outstandingPromptBytes + byteSize
+        > this.promptQueueLimits.maxOutstandingBytesPerSession
+      ) {
+        throw new FlexHarnessQueueFullError(
+          `Session "${sessionId}" has reached its outstanding prompt byte limit.`,
+        );
+      }
+      if (
+        scheduleKey
+        && [...stored.outstandingPromptsById.values()]
+          .some((entry) => entry.scheduleKey === scheduleKey)
+      ) {
+        throw new FlexHarnessSessionBusyError(sessionId, `already has scheduled key "${scheduleKey}"`);
+      }
+      let resolveCompletion!: (result: IFlexPromptResult) => void;
+      let rejectCompletion!: (error: unknown) => void;
+      const completion = new Promise<IFlexPromptResult>((resolve, reject) => {
+        resolveCompletion = resolve;
+        rejectCompletion = reject;
+      });
+      void completion.catch(() => undefined);
+      let resolveStarted!: (admission: IFlexPromptAdmission) => void;
+      let rejectStarted!: (error: unknown) => void;
+      const started = new Promise<IFlexPromptAdmission>((resolve, reject) => {
+        resolveStarted = resolve;
+        rejectStarted = reject;
+      });
+      void started.catch(() => undefined);
+      const queued: IQueuedPrompt = {
+        state,
+        stored,
+        scopeId,
+        scope: resolved.scope.scope,
+        sessionId,
+        queueId: plugins.crypto.randomUUID(),
+        queueSequence: ++this.promptQueueSequence,
+        status: 'queued',
+        queuedAt: new Date().toISOString(),
+        ...(scheduleKey === undefined ? {} : { scheduleKey, debounceMs }),
+        prompt: normalizedPrompt,
+        options: normalizedOptions,
+        byteSize,
+        completion,
+        resolveCompletion,
+        rejectCompletion,
+        started,
+        resolveStarted,
+        rejectStarted,
+      };
+      stored.promptQueue.push(queued);
+      stored.outstandingPromptsById.set(queued.queueId, queued);
+      stored.outstandingPromptBytes += byteSize;
+      this.emitPromptQueueEvent(queued, 'prompt.queued');
+      this.schedulePromptQueueDrain(state, stored);
+      return {
+        admission: Object.freeze({ queueId: queued.queueId, completion }),
+        started,
+      };
+    } finally {
+      pendingOwner.controller.signal.removeEventListener('abort', abortAdmission);
+      this.pendingPromptAdmissionOwners.delete(pendingOwner);
+      releasePendingAdmission();
+      pendingOwner.resolveSettled();
+    }
+  }
+
+  private reservePendingPromptAdmission(byteSize: number): () => void {
+    if (this.pendingPromptAdmissions >= this.promptQueueLimits.maxPendingAdmissions) {
+      throw new FlexHarnessQueueFullError('FlexHarness has reached its pending prompt admission limit.');
+    }
+    if (
+      this.pendingPromptAdmissionBytes + byteSize
+      > this.promptQueueLimits.maxPendingAdmissionBytes
+    ) {
+      throw new FlexHarnessQueueFullError('FlexHarness has reached its pending prompt admission byte limit.');
+    }
+    this.pendingPromptAdmissions++;
+    this.pendingPromptAdmissionBytes += byteSize;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.pendingPromptAdmissions--;
+      this.pendingPromptAdmissionBytes -= byteSize;
+    };
+  }
+
+  private schedulePromptQueueDrain(state: IStorageState, stored: IStoredSessionState): void {
+    if (stored.promptQueueDrain) return;
+    let drain!: Promise<void>;
+    drain = Promise.resolve()
+      .then(() => this.drainPromptQueue(state, stored))
+      .finally(() => {
+        if (stored.promptQueueDrain === drain) delete stored.promptQueueDrain;
+        if (
+          stored.promptQueue.length > 0
+          && !state.activeRuns.has(stored.session.sessionId)
+          && state.lifecycle === 'active'
+          && state.sessions.get(stored.session.sessionId) === stored
+        ) this.schedulePromptQueueDrain(state, stored);
+      });
+    stored.promptQueueDrain = drain;
+    void drain.catch(() => undefined);
+  }
+
+  private async drainPromptQueue(state: IStorageState, stored: IStoredSessionState): Promise<void> {
+    while (
+      state.lifecycle === 'active'
+      && state.sessions.get(stored.session.sessionId) === stored
+      && !state.activeRuns.has(stored.session.sessionId)
+    ) {
+      const queued = stored.promptQueue.shift();
+      if (!queued) return;
+      if (stored.outstandingPromptsById.get(queued.queueId) !== queued) continue;
+      queued.status = 'starting';
+      queued.runId = plugins.crypto.randomUUID();
+      queued.startedAt = new Date().toISOString();
+      const run = this.createActiveRun(queued);
+      state.activeRuns.set(queued.sessionId, run);
+      try {
+        await this.promoteQueuedPrompt(queued, run);
+        return;
+      } catch (error) {
+        if (state.activeRuns.get(queued.sessionId) === run) state.activeRuns.delete(queued.sessionId);
+        const cancellation = isAbortError(error);
+        this.finishQueuedPrompt(queued, cancellation ? 'cancelled' : 'failed', error);
+        if (state.lifecycle !== 'active') return;
+      }
+    }
+  }
+
+  private createActiveRun(queued: IQueuedPrompt): IActiveRun {
+    return {
+      state: queued.state,
+      stored: queued.stored,
+      scopeId: queued.scopeId,
+      scope: queued.scope,
+      sessionId: queued.sessionId,
+      queueId: queued.queueId,
+      runId: queued.runId!,
       userMessageId: plugins.crypto.randomUUID(),
       assistantMessageId: plugins.crypto.randomUUID(),
       controller: new AbortController(),
-      ...(scheduleKey === undefined ? {} : { scheduleKey, debounceMs }),
+      ...(queued.scheduleKey === undefined
+        ? {}
+        : { scheduleKey: queued.scheduleKey, debounceMs: queued.debounceMs }),
       callbackEventCount: 0,
       callbackOutputBytes: 0,
       callbackParts: [],
@@ -1368,40 +1653,59 @@ export class FlexHarness<TScope = unknown> {
       toolPartIds: new Map(),
       pendingPermissionIds: new Set(),
       phase: 'admitting',
-      completion,
-      resolveCompletion,
-      rejectCompletion,
+      completion: queued.completion,
     };
-    state.activeRuns.set(sessionId, run);
+  }
+
+  private assertPromptPromotion(queued: IQueuedPrompt, run: IActiveRun): void {
+    if (run.controller.signal.aborted) {
+      throw run.controller.signal.reason ?? new FlexHarnessAbortError();
+    }
+    this.assertStateAcceptingWork(run.state);
+    if (
+      run.state.sessions.get(run.sessionId) !== run.stored
+      || run.stored.outstandingPromptsById.get(run.queueId) !== queued
+      || run.state.activeRuns.get(run.sessionId) !== run
+    ) throw this.trustInternalError(new FlexHarnessAbortError('The prompt was retired during admission.'));
+  }
+
+  private async promoteQueuedPrompt(queued: IQueuedPrompt, run: IActiveRun): Promise<void> {
+    const prompt = queued.prompt!;
+    const options = queued.options!;
     let projectionReserved = false;
     try {
-      run.transaction = await stored.agentSession.beginGeneration(
+      run.transaction = await run.stored.agentSession.beginGeneration(
         cloneSerializable(prompt.modelMessage.content) as Parameters<
           plugins.IAgentSession['beginGeneration']
         >[0],
         { generationId: run.runId },
       );
+      this.assertPromptPromotion(queued, run);
       const reservation = this.createReservation(run, prompt);
-      await this.mutateProjection(state, stored, () => {
-        stored.messages.push(reservation.userMessage, reservation.assistantMessage);
+      await this.mutateProjection(run.state, run.stored, () => {
+        run.stored.messages.push(reservation.userMessage, reservation.assistantMessage);
       });
       projectionReserved = true;
       run.reservedUserMessage = publicSnapshot(reservation.userMessage);
       run.reservedAssistantMessage = publicSnapshot(reservation.assistantMessage);
-      await this.mutateScope(state, () => {
-        if (state.tombstones.has(sessionId) || state.sessions.get(sessionId) !== stored) {
+      this.assertPromptPromotion(queued, run);
+      await this.mutateScope(run.state, () => {
+        if (run.controller.signal.aborted) {
+          throw run.controller.signal.reason ?? new FlexHarnessAbortError();
+        }
+        if (run.state.tombstones.has(run.sessionId) || run.state.sessions.get(run.sessionId) !== run.stored) {
           throw new FlexHarnessAbortError('The session was deleted during prompt admission.');
         }
-        stored.session.status = scheduleKey ? 'scheduled' : 'running';
-        stored.session.activity = {
+        run.stored.session.status = run.scheduleKey ? 'scheduled' : 'running';
+        run.stored.session.activity = {
           runId: run.runId,
-          status: scheduleKey ? 'scheduled' : 'running',
+          status: run.scheduleKey ? 'scheduled' : 'running',
           startedAt: reservation.userMessage.createdAt,
         };
-        stored.session.updatedAt = reservation.userMessage.createdAt;
+        run.stored.session.updatedAt = reservation.userMessage.createdAt;
       });
     } catch (error) {
-      if (containsStoreCommitUncertainty(error)) state.lifecycle = 'fenced';
+      if (containsStoreCommitUncertainty(error)) run.state.lifecycle = 'fenced';
       const safeError = this.projectExternalError(run, error, projectionReserved ? 'persistence' : 'agentSession');
       let cleanupErrors: unknown[] = [];
       let cleanupFailure: unknown;
@@ -1410,30 +1714,28 @@ export class FlexHarness<TScope = unknown> {
       } catch (rollbackError) {
         cleanupFailure = rollbackError;
       }
-      if (state.lifecycle === 'fenced' && cleanupFailure === undefined) {
+      if (run.state.lifecycle === 'fenced' && cleanupFailure === undefined) {
         const combined = combineErrors([safeError, ...cleanupErrors]);
         try {
-          await this.fenceNamespace(state, run, combined);
+          await this.fenceNamespace(run.state, run, combined);
         } catch (fenceError) {
           cleanupFailure = fenceError;
         }
       }
-      if (state.activeRuns.get(sessionId) === run) state.activeRuns.delete(sessionId);
       const rejection = cleanupFailure
         ?? (cleanupErrors.length > 0 ? combineErrors([safeError, ...cleanupErrors]) : safeError);
-      run.rejectCompletion(rejection);
       throw rejection;
     }
 
-    const runType = scheduleKey ? 'run.scheduled' : 'run.started';
-    this.emitEvent(scopeId, sessionId, {
+    const runType = run.scheduleKey ? 'run.scheduled' : 'run.started';
+    this.emitEvent(run.scopeId, run.sessionId, {
       type: runType,
       runId: run.runId,
       messageId: run.userMessageId,
-      session: publicSnapshot(stored.session),
+      session: publicSnapshot(run.stored.session),
     });
     for (const message of [run.reservedUserMessage!, run.reservedAssistantMessage!]) {
-      this.emitEvent(scopeId, sessionId, {
+      this.emitEvent(run.scopeId, run.sessionId, {
         type: 'message.created',
         runId: run.runId,
         messageId: message.messageId,
@@ -1441,22 +1743,144 @@ export class FlexHarness<TScope = unknown> {
       });
     }
 
-    run.phase = scheduleKey ? 'scheduled' : 'running';
+    queued.status = run.scheduleKey ? 'scheduled' : 'starting';
+    this.emitPromptQueueEvent(queued, 'prompt.started');
+    queued.resolveStarted(Object.freeze({
+      queueId: queued.queueId,
+      runId: run.runId,
+      completion: queued.completion,
+    }));
+    run.phase = run.scheduleKey ? 'scheduled' : 'running';
     const generateOptions = {
       transaction: run.transaction,
       abort: run.controller.signal,
       prepare: (context: { generationId: string; abortSignal: AbortSignal }) =>
         this.prepareGeneration(run, options, context.abortSignal),
     };
-    const generation = scheduleKey
-      ? stored.agentSession.scheduleGenerate({
-          key: scheduleKey,
-          debounceMs,
+    const generation = run.scheduleKey
+      ? run.stored.agentSession.scheduleGenerate({
+          key: run.scheduleKey,
+          debounceMs: run.debounceMs,
           ...generateOptions,
         })
-      : stored.agentSession.generate(generateOptions);
-    void this.executeRun(run, generation).then(run.resolveCompletion, run.rejectCompletion);
-    return Object.freeze({ runId: run.runId, completion: run.completion });
+      : run.stored.agentSession.generate(generateOptions);
+    const execution = this.executeRun(run, generation).then(
+      (result) => this.finishQueuedPrompt(queued, 'completed', undefined, result),
+      (error) => this.finishQueuedPrompt(
+        queued,
+        isAbortError(error) ? 'cancelled' : 'failed',
+        error,
+      ),
+    ).finally(() => this.schedulePromptQueueDrain(run.state, run.stored));
+    void execution.catch(() => undefined);
+  }
+
+  private projectPromptQueueEntry(queued: IQueuedPrompt): IFlexPromptQueueEntry {
+    return {
+      queueId: queued.queueId,
+      queueSequence: queued.queueSequence,
+      scopeId: queued.scopeId,
+      sessionId: queued.sessionId,
+      status: queued.status,
+      queuedAt: queued.queuedAt,
+      ...(queued.runId ? { runId: queued.runId } : {}),
+      ...(queued.scheduleKey ? { scheduleKey: queued.scheduleKey } : {}),
+      ...(queued.startedAt ? { startedAt: queued.startedAt } : {}),
+    };
+  }
+
+  private promptQueueEntry(
+    stored: IStoredSessionState,
+    queueId: string,
+  ): IFlexPromptQueueEntry | undefined {
+    const outstanding = stored.outstandingPromptsById.get(queueId);
+    return outstanding
+      ? this.projectPromptQueueEntry(outstanding)
+      : stored.terminalPromptQueueEntries.get(queueId);
+  }
+
+  private emitPromptQueueEvent(
+    queued: IQueuedPrompt,
+    type: 'prompt.queued' | 'prompt.started' | 'prompt.running' | 'prompt.finished',
+    entry: IFlexPromptQueueEntry = this.projectPromptQueueEntry(queued),
+  ): void {
+    this.emitEvent(queued.scopeId, queued.sessionId, {
+      type,
+      queueId: queued.queueId,
+      ...(entry.runId ? { runId: entry.runId } : {}),
+      entry: publicSnapshot(entry),
+    });
+  }
+
+  private finishQueuedPrompt(
+    queued: IQueuedPrompt,
+    status: 'completed' | 'failed' | 'cancelled',
+    error?: unknown,
+    result?: IFlexPromptResult,
+  ): void {
+    const stored = queued.stored;
+    if (stored.outstandingPromptsById.get(queued.queueId) !== queued) return;
+    stored.promptQueue = stored.promptQueue.filter((entry) => entry !== queued);
+    stored.outstandingPromptsById.delete(queued.queueId);
+    stored.outstandingPromptBytes = Math.max(0, stored.outstandingPromptBytes - queued.byteSize);
+    delete queued.prompt;
+    delete queued.options;
+    const terminal: IFlexPromptQueueEntry = {
+      ...this.projectPromptQueueEntry(queued),
+      status,
+      finishedAt: new Date().toISOString(),
+      ...(error === undefined ? {} : { error: errorToInfo(error) }),
+    };
+    stored.terminalPromptQueueEntries.set(queued.queueId, terminal);
+    while (
+      stored.terminalPromptQueueEntries.size
+      > this.promptQueueLimits.maxTerminalEntriesPerSession
+    ) {
+      const oldest = stored.terminalPromptQueueEntries.keys().next().value as string | undefined;
+      if (!oldest) break;
+      stored.terminalPromptQueueEntries.delete(oldest);
+    }
+    this.emitPromptQueueEvent(queued, 'prompt.finished', terminal);
+    if (status === 'completed') {
+      if (!result) throw new Error('A completed queued prompt requires a result.');
+      queued.resolveCompletion(result);
+    } else {
+      const rejection = error ?? this.trustInternalError(new FlexHarnessAbortError());
+      queued.rejectStarted(rejection);
+      queued.rejectCompletion(rejection);
+    }
+  }
+
+  private cancelQueuedPrompt(queued: IQueuedPrompt, reason: FlexHarnessAbortError): boolean {
+    if (queued.stored.outstandingPromptsById.get(queued.queueId) !== queued) return false;
+    if (queued.status === 'queued') {
+      this.finishQueuedPrompt(queued, 'cancelled', reason);
+      this.schedulePromptQueueDrain(queued.state, queued.stored);
+      return true;
+    }
+    const run = queued.state.activeRuns.get(queued.sessionId);
+    if (!run || run.queueId !== queued.queueId) return false;
+    if (run.phase === 'finalizing' || run.phase === 'promoting') return false;
+    this.cancelRun(run, reason);
+    return true;
+  }
+
+  private cancelStoredPromptQueue(
+    stored: IStoredSessionState,
+    reason: FlexHarnessAbortError,
+    excludedQueueId?: string,
+  ): void {
+    for (const queued of [...stored.outstandingPromptsById.values()]) {
+      if (queued.queueId === excludedQueueId) continue;
+      this.cancelQueuedPrompt(queued, reason);
+    }
+  }
+
+  private purgeStoredPromptQueue(stored: IStoredSessionState): void {
+    stored.promptQueue.length = 0;
+    stored.outstandingPromptsById.clear();
+    stored.terminalPromptQueueEntries.clear();
+    stored.outstandingPromptBytes = 0;
   }
 
   private async executeRun(
@@ -1597,7 +2021,13 @@ export class FlexHarness<TScope = unknown> {
     options: IFlexPromptOptions,
     signal: AbortSignal,
   ): Promise<plugins.IAgentGenerationLease> {
+    signal.throwIfAborted();
     run.phase = 'running';
+    const queued = run.stored.outstandingPromptsById.get(run.queueId);
+    if (queued && (queued.status === 'starting' || queued.status === 'scheduled')) {
+      queued.status = 'running';
+      this.emitPromptQueueEvent(queued, 'prompt.running');
+    }
     const modelOutcome = Promise.resolve()
       .then(() => this.modelResolver.resolveModel({
         scopeId: run.scopeId,
@@ -2390,6 +2820,7 @@ export class FlexHarness<TScope = unknown> {
     if (run.internalFailure === undefined) run.ownerCancellation ??= reason;
     this.rejectRunPermissions(run.state, run, reason);
     if (!run.controller.signal.aborted) run.controller.abort(reason);
+    if (run.phase === 'admitting') return;
     if (run.scheduleKey) run.stored.agentSession.cancelScheduledGeneration(run.scheduleKey, reason);
     else run.stored.agentSession.abortCurrentGeneration(reason);
   }
@@ -2731,6 +3162,10 @@ export class FlexHarness<TScope = unknown> {
       agentEventStoreReleased: true,
       executionContextCloseCompleted: true,
       jobStoreReleased: true,
+      promptQueue: [],
+      outstandingPromptsById: new Map(),
+      terminalPromptQueueEntries: new Map(),
+      outstandingPromptBytes: 0,
     };
   }
 
@@ -2813,6 +3248,10 @@ export class FlexHarness<TScope = unknown> {
         executionContextCloseCompleted: executionContextHandle?.close === undefined,
         jobStoreReleased: this.stores.jobs.releaseSession === undefined,
         jobs: executionContextHandle?.context.jobs,
+        promptQueue: [],
+        outstandingPromptsById: new Map(),
+        terminalPromptQueueEntries: new Map(),
+        outstandingPromptBytes: 0,
       };
       const agentSessionOptions: plugins.IAgentSessionOptions & {
         transactionOutcomeErrorProjector: (error: unknown) => string;
@@ -3325,6 +3764,7 @@ export class FlexHarness<TScope = unknown> {
     if (retained) {
       const errors: unknown[] = [];
       const reason = this.trustInternalError(new FlexHarnessAbortError('The session was deleted.'));
+      this.cancelStoredPromptQueue(retained.stored, reason);
       const run = state.activeRuns.get(sessionId);
       if (run) this.cancelRun(run, reason);
       if (!retained.stored.agentSessionAbortCompleted) {
@@ -3346,6 +3786,10 @@ export class FlexHarness<TScope = unknown> {
           errors.push(settled[0].reason);
         }
       }
+      if (retained.stored.promptQueueDrain) {
+        const settled = await Promise.allSettled([retained.stored.promptQueueDrain]);
+        if (settled[0].status === 'rejected') errors.push(settled[0].reason);
+      }
       try {
         await this.closeStoredSession(retained.stored);
       } catch (error) {
@@ -3358,6 +3802,7 @@ export class FlexHarness<TScope = unknown> {
         ));
       }
       if (errors.length > 0) throw combineErrors(errors);
+      this.purgeStoredPromptQueue(retained.stored);
     }
     if (!retained?.domainsCompleted) {
       if (this.hasOrphanedSessionResources(state.storageKey, sessionId)) {
@@ -3384,6 +3829,13 @@ export class FlexHarness<TScope = unknown> {
     const reason = this.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.'));
     const cleanupErrors: unknown[] = [];
     try {
+      for (const stored of state.sessions.values()) {
+        this.cancelStoredPromptQueue(
+          stored,
+          reason,
+          stored === currentRun.stored ? currentRun.queueId : undefined,
+        );
+      }
       const otherRuns = [...state.activeRuns.values()].filter((run) => run !== currentRun);
       for (const run of otherRuns) this.cancelRun(run, reason);
       const runResults = await Promise.allSettled(otherRuns.map((run) => run.completion));
@@ -3432,6 +3884,7 @@ export class FlexHarness<TScope = unknown> {
             ));
           }
         }
+        if (stored !== currentRun.stored) this.purgeStoredPromptQueue(stored);
       }
       cleanupErrors.push(...await this.settleDetachedCleanups(state, detachedCleanupAttempts));
       state.fenceAdditionalErrors.length = 0;
@@ -3677,6 +4130,7 @@ export class FlexHarness<TScope = unknown> {
     if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
     const detachedCleanupAttempts = this.beginDetachedCleanupSettlement(state);
     const errors: unknown[] = [];
+    for (const stored of state.sessions.values()) this.cancelStoredPromptQueue(stored, reason);
     for (const run of state.activeRuns.values()) {
       if (run.phase !== 'finalizing' && run.phase !== 'promoting') this.cancelRun(run, reason);
     }
@@ -3704,6 +4158,7 @@ export class FlexHarness<TScope = unknown> {
     await Promise.all([...state.sessions.values()].flatMap((stored) => [
       stored.projectionQueue,
       stored.permissionQueue,
+      ...(stored.promptQueueDrain ? [stored.promptQueueDrain] : []),
     ]));
     const tombstoneAttempts = [...state.tombstoneCleanups.entries()];
     const tombstoneResults = await Promise.allSettled(
@@ -3726,6 +4181,7 @@ export class FlexHarness<TScope = unknown> {
           'lifecycle-close',
         ));
       }
+      this.purgeStoredPromptQueue(stored);
     }
     for (const sessionId of [...state.tombstones.keys()]) {
       if (attemptedTombstones.has(sessionId)) continue;
@@ -3753,6 +4209,14 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private async disposeInternal(): Promise<void> {
+    const pendingAdmissions = [...this.pendingPromptAdmissionOwners];
+    const pendingAdmissionReason = this.trustInternalError(new FlexHarnessAbortError(
+      'The prompt admission was aborted because FlexHarness was disposed.',
+    ));
+    for (const pending of pendingAdmissions) {
+      if (!pending.controller.signal.aborted) pending.controller.abort(pendingAdmissionReason);
+    }
+    await Promise.all(pendingAdmissions.map((pending) => pending.settled));
     const loads = [...this.stateLoads.entries()];
     const results = await Promise.allSettled(loads.map(([storageKey, stateLoad]) =>
       this.drainStorage(
@@ -3878,10 +4342,10 @@ export class FlexHarness<TScope = unknown> {
     const stored = this.requireSession(state, sessionId);
     const pending = [...state.pendingPermissions.values()].some((entry) =>
       !entry.settled && entry.request.sessionId === sessionId);
-    if (state.activeRuns.has(sessionId) || pending) {
+    if (stored.outstandingPromptsById.size > 0 || pending) {
       throw new FlexHarnessSessionBusyError(
         sessionId,
-        'cannot be changed while it has an active run or pending permission',
+        'cannot be changed while it has an outstanding prompt or pending permission',
       );
     }
     return stored;