@modelprofile.com/flexharness 10.24.0 → 10.24.1

package/ts/classes.flexharness.prompts.ts

@@ -0,0 +1,857 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessNotFoundError,
+  FlexHarnessQueueFullError,
+  FlexHarnessSessionBusyError,
+  FlexHarnessSlashCommandReentryError,
+  FlexHarnessSteerRejectedError,
+  FlexHarnessStoreCommitUncertainError,
+  FlexHarnessValidationError,
+  errorToInfo,
+} from './errors.js';
+import type {
+  IFlexAgentContextInvocation,
+  IFlexSteerAdmission,
+  IFlexSteerInput,
+  IFlexPromptAdmission,
+  IFlexPromptQueueAdmission,
+  IFlexPromptQueueEntry,
+  IFlexPromptOptions,
+  IFlexPromptResult,
+  IFlexScheduledPromptAdmission,
+  IFlexSchedulePromptOptions,
+  TFlexPrompt,
+} from './interfaces.js';
+import { cloneSerializable } from './utils.json.js';
+import { normalizeFlexPrompt, type INormalizedFlexPrompt } from './utils.prompt.js';
+import { jsonBytes, publicSnapshot, requireTransferIdentifier } from './utils.transfer.js';
+import { validateIdentifier, validatePromptOptions } from './utils.validation.js';
+import { createSessionMetricsOperation } from './utils.sessionmetrics.js';
+import type {
+  IStoredSessionState,
+  IStorageState,
+  IActiveRun,
+  IDelegatedRunAdmissionSeed,
+  IQueuedPrompt,
+  IPendingPromptAdmission,
+} from './interfaces.flexharness.js';
+import { combineErrors, isAbortError } from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+const maxScheduleDebounceMs = 24 * 60 * 60 * 1000;
+
+function containsStoreCommitUncertainty(error: unknown, seen = new Set<unknown>()): boolean {
+  if (error instanceof FlexHarnessStoreCommitUncertainError) return true;
+  if (!(error instanceof Error) || seen.has(error)) return false;
+  seen.add(error);
+  try {
+    if (error instanceof AggregateError) {
+      for (const nested of error.errors) {
+        if (containsStoreCommitUncertainty(nested, seen)) return true;
+      }
+    }
+    return containsStoreCommitUncertainty(error.cause, seen);
+  } catch {
+    return false;
+  }
+}
+
+/** The prompt queue: admission, scheduling, promotion and cancellation of prompts and steers. */
+export class FlexHarnessPromptQueue<TScope> {
+  public readonly pendingPromptAdmissionOwners = new Set<IPendingPromptAdmission>();
+  private promptQueueSequence = 0;
+  public pendingPromptAdmissions = 0;
+  public pendingPromptAdmissionBytes = 0;
+
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public promptAdmissionByteSize(
+    prompt: TFlexPrompt,
+    options: IFlexPromptOptions,
+    scheduleKey?: string,
+    debounceMs?: number,
+  ): number {
+    return jsonBytes({
+      prompt: normalizeFlexPrompt(prompt),
+      options: cloneSerializable(options),
+      scheduleKey,
+      debounceMs,
+    });
+  }
+
+  public isSessionRuntimeIdle(state: IStorageState, stored: IStoredSessionState): boolean {
+    return stored.session.status === 'idle'
+      && !state.activeRuns.has(stored.session.sessionId)
+      && stored.outstandingPromptsById.size === 0;
+  }
+
+  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> {
+    validatePromptOptions(options, false);
+    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(
+    scopeId: string,
+    sessionId: string,
+    scheduleKey: string,
+    prompt: TFlexPrompt,
+    options: IFlexSchedulePromptOptions = {},
+  ): Promise<IFlexScheduledPromptAdmission> {
+    validateIdentifier(scheduleKey, 'scheduleKey');
+    requireTransferIdentifier(scheduleKey, 'scheduleKey');
+    validatePromptOptions(options, true);
+    const debounceMs = options.debounceMs ?? 50;
+    if (!Number.isSafeInteger(debounceMs) || debounceMs < 0 || debounceMs > maxScheduleDebounceMs) {
+      throw new FlexHarnessValidationError(
+        `debounceMs must be an integer from 0 through ${maxScheduleDebounceMs}.`,
+      );
+    }
+    const queued = await this.enqueuePromptInternal(
+      scopeId,
+      sessionId,
+      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.core.resolveState(scopeId);
+    this.core.assertStateAcceptingWork(state);
+    const stored = this.core.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.core.resolveState(scopeId);
+    this.core.assertStateAcceptingWork(state);
+    const stored = this.core.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 { scope, state } = await this.core.resolveState(scopeId);
+    const stored = this.core.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.core.trustInternalError(new FlexHarnessAbortError('The queued prompt was cancelled.')),
+      this.core.compaction.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+    );
+  }
+
+  public async cancelScheduledPrompt(
+    scopeId: string,
+    sessionId: string,
+    scheduleKey: string,
+  ): Promise<boolean> {
+    validateIdentifier(scheduleKey, 'scheduleKey');
+    const { scope, state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    const queued = [...stored.outstandingPromptsById.values()]
+      .find((entry) => entry.scheduleKey === scheduleKey);
+    if (!queued) return false;
+    const cancellation = this.core.trustInternalError(new FlexHarnessAbortError('The scheduled run was cancelled.'));
+    return this.cancelQueuedPrompt(
+      queued,
+      cancellation,
+      this.core.compaction.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+    );
+  }
+
+  public async steerPrompt(
+    scopeId: string,
+    sessionId: string,
+    queueId: string,
+    steer: IFlexSteerInput,
+  ): Promise<IFlexSteerAdmission> {
+    validateIdentifier(queueId, 'queueId');
+    requireTransferIdentifier(queueId, 'queueId');
+    validateIdentifier(steer.steerId, 'steerId');
+    requireTransferIdentifier(steer.steerId, 'steerId');
+    this.core.assertOpen();
+    const prompt = normalizeFlexPrompt(steer.prompt);
+    const byteSize = this.promptAdmissionByteSize(steer.prompt, {});
+    const { state } = await this.core.resolveState(scopeId);
+    this.core.assertStateAcceptingWork(state);
+    const stored = this.core.requireSession(state, sessionId);
+    this.core.assertSessionWritable(stored);
+    if (stored.session.agent !== undefined) {
+      throw new FlexHarnessValidationError(
+        'Subagent sessions can only be prompted through the foreground delegate tool.',
+      );
+    }
+    const run = state.activeRuns.get(sessionId);
+    if (!run || run.queueId !== queueId) {
+      if (stored.outstandingPromptsById.has(queueId) || stored.terminalPromptQueueEntries.has(queueId)) {
+        throw new FlexHarnessSteerRejectedError('not-running', steer.steerId);
+      }
+      throw new FlexHarnessNotFoundError('Prompt queue entry', queueId);
+    }
+    return this.admitRunSteer(run, steer, prompt, byteSize);
+  }
+
+  /** The shared synchronous admission point; neither entrypoint starts or resumes a run. */
+  public admitRunSteer(
+    run: IActiveRun,
+    steer: IFlexSteerInput,
+    prompt: INormalizedFlexPrompt,
+    byteSize: number,
+  ): IFlexSteerAdmission {
+    if (
+      run.phase === 'closing'
+      || run.phase === 'finalizing'
+      || run.phase === 'promoting'
+      || run.callbacksClosed
+      || run.controller.signal.aborted
+      || run.stop.signal.aborted
+      || run.state.activeRuns.get(run.sessionId) !== run
+    ) throw new FlexHarnessSteerRejectedError('not-running', steer.steerId);
+    const steering = run.steering;
+    if (!steering.input.closed && !steering.accepted.has(steer.steerId)) {
+      if (
+        steering.accepted.size - steering.applied.size
+        >= this.core.promptQueueLimits.maxOutstandingPromptsPerSession
+      ) {
+        throw new FlexHarnessQueueFullError(`Session "${run.sessionId}" has reached its pending steer limit.`);
+      }
+      // Pending steers hold outstanding prompt bytes of the session until they are taken in.
+      if (
+        steering.stored.outstandingPromptBytes + byteSize
+        > this.core.promptQueueLimits.maxOutstandingBytesPerSession
+      ) {
+        throw new FlexHarnessQueueFullError(
+          `Session "${run.sessionId}" has reached its outstanding prompt byte limit.`,
+        );
+      }
+    }
+    try {
+      steering.input.add({
+        inputId: steer.steerId,
+        content: cloneSerializable(prompt.modelMessage.content) as Parameters<
+          plugins.IAgentSession['beginGeneration']
+        >[0],
+      });
+    } catch (error) {
+      if (error instanceof plugins.AgentPendingInputRejectedError) {
+        throw new FlexHarnessSteerRejectedError(
+          error.reason === 'duplicate' ? 'duplicate' : 'not-running',
+          steer.steerId,
+        );
+      }
+      throw error;
+    }
+    steering.accepted.set(steer.steerId, { prompt, byteSize });
+    steering.stored.outstandingPromptBytes += byteSize;
+    this.core.emitEvent(run.scopeId, run.stored.session, {
+      type: 'prompt.steer.accepted',
+      queueId: run.queueId,
+      runId: run.runId,
+      steerId: steer.steerId,
+    });
+    return { steerId: steer.steerId, queueId: run.queueId, runId: run.runId };
+  }
+
+  public async enqueuePromptInternal(
+    scopeId: string,
+    sessionId: string,
+    prompt: TFlexPrompt,
+    options: IFlexPromptOptions,
+    scheduleKey?: string,
+    debounceMs?: number,
+    delegationSeed?: IDelegatedRunAdmissionSeed,
+    admissionSignal?: AbortSignal,
+    slashCommandAdmission = false,
+  ): Promise<{
+    admission: IFlexPromptQueueAdmission;
+    started: Promise<IFlexPromptAdmission>;
+    queued?: IQueuedPrompt;
+  }> {
+    this.core.assertOpen();
+    const normalizedPrompt = normalizeFlexPrompt(prompt);
+    const normalizedOptions = cloneSerializable(options);
+    const byteSize = this.promptAdmissionByteSize(prompt, options, scheduleKey, debounceMs);
+    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);
+    const admissionSignals = [
+      pendingOwner.controller.signal,
+      ...(admissionSignal === undefined ? [] : [admissionSignal]),
+    ];
+    let abortAdmission!: () => void;
+    const abortPromise = new Promise<never>((_resolve, reject) => {
+      abortAdmission = () => {
+        const aborted = admissionSignals.find((signal) => signal.aborted);
+        reject(aborted?.reason ?? new FlexHarnessAbortError());
+      };
+      for (const signal of admissionSignals) {
+        signal.addEventListener('abort', abortAdmission, { once: true });
+      }
+      if (admissionSignals.some((signal) => signal.aborted)) abortAdmission();
+    });
+    try {
+      const resolved = await Promise.race([this.core.resolveState(scopeId), abortPromise]);
+      const state = resolved.state;
+      await Promise.race([state.scopeQueue, abortPromise]);
+      if (admissionSignal?.aborted) {
+        throw admissionSignal.reason ?? new FlexHarnessAbortError();
+      }
+      this.core.assertStateAcceptingWork(state);
+      const stored = this.core.requireSession(state, sessionId);
+      this.core.assertSessionWritable(stored);
+      const sessionKey = this.core.commands.slashCommandSessionKey(state.storageKey, sessionId);
+      const invocationOwner = this.core.commands.slashCommandInvocationContext.getStore();
+      if (invocationOwner?.sessionKey === sessionKey) {
+        throw this.core.trustInternalError(new FlexHarnessSlashCommandReentryError(sessionId));
+      }
+      if (!slashCommandAdmission && this.core.commands.activeSlashCommandExecutions.has(sessionKey)) {
+        throw new FlexHarnessSessionBusyError(
+          sessionId,
+          'already has an active slash command execution',
+        );
+      }
+      if (stored.pendingReversion) {
+        throw new FlexHarnessSessionBusyError(sessionId, 'has a pending reversion operation');
+      }
+      if (stored.session.agent !== undefined && delegationSeed === undefined) {
+        throw new FlexHarnessValidationError(
+          'Subagent sessions can only be prompted through the foreground delegate tool.',
+        );
+      }
+      if (delegationSeed !== undefined) {
+        this.core.admission.assertDelegatedRunAdmissionOwnership(delegationSeed, state, stored, scopeId);
+      }
+      if (stored.outstandingPromptsById.size >= this.core.promptQueueLimits.maxOutstandingPromptsPerSession) {
+        throw new FlexHarnessQueueFullError(
+          `Session "${sessionId}" has reached its outstanding prompt limit.`,
+        );
+      }
+      if (
+        stored.outstandingPromptBytes + byteSize
+        > this.core.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: delegationSeed === undefined ? resolved.scope.scope : delegationSeed.scope,
+        sessionId,
+        queueId: plugins.crypto.randomUUID(),
+        queueSequence: ++this.promptQueueSequence,
+        status: 'queued',
+        queuedAt: new Date().toISOString(),
+        ...(scheduleKey === undefined ? {} : { scheduleKey, debounceMs }),
+        prompt: normalizedPrompt,
+        options: normalizedOptions,
+        ...(delegationSeed === undefined ? {} : { delegationSeed }),
+        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,
+        queued,
+      };
+    } finally {
+      for (const signal of admissionSignals) {
+        signal.removeEventListener('abort', abortAdmission);
+      }
+      this.pendingPromptAdmissionOwners.delete(pendingOwner);
+      releasePendingAdmission();
+      pendingOwner.resolveSettled();
+    }
+  }
+
+  private reservePendingPromptAdmission(byteSize: number): () => void {
+    if (this.pendingPromptAdmissions >= this.core.promptQueueLimits.maxPendingAdmissions) {
+      throw new FlexHarnessQueueFullError('FlexHarness has reached its pending prompt admission limit.');
+    }
+    if (
+      this.pendingPromptAdmissionBytes + byteSize
+      > this.core.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.core.runs.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 assertPromptPromotion(queued: IQueuedPrompt, run: IActiveRun): void {
+    if (run.controller.signal.aborted) {
+      throw run.controller.signal.reason ?? new FlexHarnessAbortError();
+    }
+    this.core.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.core.trustInternalError(new FlexHarnessAbortError('The prompt was retired during admission.'));
+    if (queued.delegationSeed) {
+      this.core.admission.assertDelegatedRunAdmissionOwnership(
+        queued.delegationSeed,
+        run.state,
+        run.stored,
+        run.scopeId,
+      );
+      if (
+        run.queueId !== queued.queueId
+        || run.runId !== queued.runId
+        || run.sessionId !== queued.delegationSeed.sessionId
+      ) {
+        throw this.core.trustInternalError(
+          new FlexHarnessAbortError('The delegated prompt lost its exact child run ownership.'),
+        );
+      }
+    }
+  }
+
+  private async promoteQueuedPrompt(queued: IQueuedPrompt, run: IActiveRun): Promise<void> {
+    const prompt = queued.prompt!;
+    const options = queued.options!;
+    let projectionReserved = false;
+    // Open from the reservation until its messages are announced or rolled back.
+    let closeReservationPublication = (): void => undefined;
+    try {
+      try {
+        this.assertPromptPromotion(queued, run);
+        await this.core.admission.acquireDelegatedRunAdmission(queued, run);
+        this.assertPromptPromotion(queued, run);
+        await this.core.reversions.commitRevertedBranch(run.state, run.stored, run.scopeId, run.scope as TScope);
+        this.assertPromptPromotion(queued, run);
+        const generationPrompt = cloneSerializable(prompt.modelMessage.content) as Parameters<
+          plugins.IAgentSession['beginGeneration']
+        >[0];
+        this.assertPromptPromotion(queued, run);
+        run.transaction = await this.core.compaction.withRunCompactorContext(
+          run,
+          () => run.stored.agentSession.beginGeneration(
+            generationPrompt,
+            { generationId: run.runId },
+          ),
+        );
+        this.assertPromptPromotion(queued, run);
+        const reservation = this.core.runs.createReservation(run, prompt);
+        closeReservationPublication = this.core.openPublication(run.state, run.sessionId);
+        run.metricsOperation = createSessionMetricsOperation(run.runId, 'generation');
+        await this.core.mutateProjection(run.state, run.stored, () => {
+          if (run.stored.metrics.pendingGenerationId !== undefined) {
+            throw new Error('Session metrics already owns a generation.');
+          }
+          run.stored.metrics.pendingGenerationId = run.runId;
+          run.stored.messages.push(reservation.userMessage, reservation.assistantMessage);
+          if (run.stored.session.agent === undefined) {
+            this.core.reversions.pruneReversionState(run.stored, true);
+            const captureId = this.core.turnReversionProvider
+              ? this.core.reversions.reversionId('capture', run.state.storageKey, run.sessionId, run.runId)
+              : undefined;
+            const protocolVersion = this.core.reversions.reversionProviderProtocolVersion() ?? 1;
+            run.stored.reversionSegments.push({
+              runId: run.runId,
+              userMessageId: reservation.userMessage.messageId,
+              status: 'capturing',
+              contextAvailable: true,
+              eventIds: [],
+              workspaceCaptured: captureId !== undefined,
+              protocolVersion,
+              provenance: captureId === undefined ? 'transcript' : 'workspace',
+              ...(captureId === undefined ? {} : { disposition: 'pending' }),
+              ...(captureId === undefined ? {} : { captureId }),
+            });
+            if (captureId) {
+              run.stored.pendingReversion = {
+                kind: 'capture',
+                runId: run.runId,
+                captureId,
+                state: 'preparing',
+                protocolVersion,
+              };
+            }
+          }
+        });
+        projectionReserved = true;
+        run.reservedUserMessage = publicSnapshot(reservation.userMessage);
+        run.reservedAssistantMessage = publicSnapshot(reservation.assistantMessage);
+        this.assertPromptPromotion(queued, run);
+        await this.core.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.');
+          }
+          run.stored.session.status = run.scheduleKey ? 'scheduled' : 'running';
+          run.stored.session.activity = {
+            runId: run.runId,
+            status: run.scheduleKey ? 'scheduled' : 'running',
+            startedAt: reservation.userMessage.createdAt,
+          };
+          run.stored.session.updatedAt = reservation.userMessage.createdAt;
+        });
+      } catch (error) {
+        if (containsStoreCommitUncertainty(error)) run.state.lifecycle = 'fenced';
+        const safeError = this.core.projectExternalError(run, error, projectionReserved ? 'persistence' : 'agentSession');
+        let cleanupErrors: unknown[] = [];
+        let cleanupFailure: unknown;
+        try {
+          await this.core.admission.closeRunDelegatedRunAdmission(
+            run,
+            !run.delegatedRunAdmissionOwner?.acquisitionDetached,
+          );
+        } catch (closeError) {
+          cleanupErrors.push(closeError);
+        }
+        try {
+          cleanupErrors.push(...await this.core.runs.rollbackAdmission(run, projectionReserved, safeError));
+        } catch (rollbackError) {
+          cleanupFailure = rollbackError;
+        }
+        if (cleanupFailure !== undefined && cleanupErrors.length > 0) {
+          cleanupFailure = combineErrors([cleanupFailure, ...cleanupErrors]);
+        }
+        if (run.state.lifecycle === 'fenced' && cleanupFailure === undefined) {
+          const combined = combineErrors([safeError, ...cleanupErrors]);
+          try {
+            await this.core.lifecycle.fenceNamespace(run.state, run, combined);
+          } catch (fenceError) {
+            cleanupFailure = fenceError;
+          }
+        }
+        const rejection = cleanupFailure
+          ?? (cleanupErrors.length > 0 ? combineErrors([safeError, ...cleanupErrors]) : safeError);
+        throw rejection;
+      }
+
+      const runType = run.scheduleKey ? 'run.scheduled' : 'run.started';
+      this.core.emitEvent(run.scopeId, run.stored.session, {
+        type: runType,
+        runId: run.runId,
+        messageId: run.userMessageId,
+        session: publicSnapshot(run.stored.session),
+      });
+      for (const message of [run.reservedUserMessage!, run.reservedAssistantMessage!]) {
+        this.core.emitEvent(run.scopeId, run.stored.session, {
+          type: 'message.created',
+          runId: run.runId,
+          messageId: message.messageId,
+          message,
+        });
+      }
+    } finally {
+      closeReservationPublication();
+    }
+
+    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,
+      stop: run.stop.signal,
+      prepare: (context: { generationId: string; abortSignal: AbortSignal }) =>
+        this.core.runs.prepareGeneration(run, options, context.abortSignal),
+      pendingInput: run.steering.input,
+      activateOnBackgroundJobs: true,
+      onCacheDispatch: (dispatch: plugins.ISmartAiCacheDispatch) => { run.cacheDispatch = dispatch; },
+      onInputApplied: (input: plugins.IAgentAppliedInput) => this.core.runs.applyRunSteer(run, input),
+      beforeFinish: (context: { abortSignal: AbortSignal }) =>
+        this.core.subagentTasks.awaitNextBackgroundSubagent(run, context.abortSignal),
+    };
+    const generation = this.core.compaction.withRunCompactorContext(run, () => run.scheduleKey
+      ? run.stored.agentSession.scheduleGenerate({
+          key: run.scheduleKey,
+          debounceMs: run.debounceMs,
+          ...generateOptions,
+        })
+      : run.stored.agentSession.generate(generateOptions));
+    const execution = this.core.runs.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);
+  }
+
+  public emitPromptQueueEvent(
+    queued: IQueuedPrompt,
+    type: 'prompt.queued' | 'prompt.started' | 'prompt.running' | 'prompt.finished',
+    entry: IFlexPromptQueueEntry = this.projectPromptQueueEntry(queued),
+  ): void {
+    this.core.emitEvent(queued.scopeId, queued.stored.session, {
+      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;
+    delete queued.delegationSeed;
+    const steering = queued.steering === undefined ? undefined : this.core.runs.closeRunSteering(queued.steering);
+    const terminal: IFlexPromptQueueEntry = {
+      ...this.projectPromptQueueEntry(queued),
+      status,
+      finishedAt: new Date().toISOString(),
+      ...(error === undefined ? {} : { error: errorToInfo(error) }),
+      keptInContext: steering?.keptInContext ?? false,
+      ...(steering === undefined || steering.unappliedSteerIds.length === 0
+        ? {}
+        : { unappliedSteerIds: [...steering.unappliedSteerIds] }),
+    };
+    stored.terminalPromptQueueEntries.set(queued.queueId, terminal);
+    while (
+      stored.terminalPromptQueueEntries.size
+      > this.core.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.core.trustInternalError(new FlexHarnessAbortError());
+      queued.rejectStarted(rejection);
+      queued.rejectCompletion(rejection);
+    }
+  }
+
+  public cancelQueuedPrompt(
+    queued: IQueuedPrompt,
+    reason: FlexHarnessAbortError,
+    context?: IFlexAgentContextInvocation<TScope>,
+  ): 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.core.runs.cancelRun(run, reason, context);
+    return true;
+  }
+
+  public cancelStoredPromptQueue(
+    stored: IStoredSessionState,
+    reason: FlexHarnessAbortError,
+    excludedQueueId?: string,
+    context?: IFlexAgentContextInvocation<unknown>,
+  ): void {
+    for (const queued of [...stored.outstandingPromptsById.values()]) {
+      if (queued.queueId === excludedQueueId) continue;
+      this.cancelQueuedPrompt(
+        queued,
+        reason,
+        context as IFlexAgentContextInvocation<TScope> | undefined,
+      );
+    }
+  }
+
+  public purgeStoredPromptQueue(stored: IStoredSessionState): void {
+    for (const queued of stored.outstandingPromptsById.values()) {
+      delete queued.prompt;
+      delete queued.options;
+      delete queued.delegationSeed;
+    }
+    stored.promptQueue.length = 0;
+    stored.outstandingPromptsById.clear();
+    stored.terminalPromptQueueEntries.clear();
+    stored.outstandingPromptBytes = 0;
+  }
+}