@modelprofile.com/flexharness 10.1.0 → 10.2.0

package/ts/classes.flexharness.ts

@@ -90,6 +90,7 @@ import type {
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
+  IFlexSessionView,
   IFlexSessionPermissionPolicyContext,
   IFlexSessionActivity,
   IFlexSessionGeneration,
@@ -360,6 +361,11 @@ interface IStorageState {
   activeRuns: Map<string, IActiveRun>;
   delegatedRunAdmissionOwners: Set<IDelegatedRunAdmissionOwner>;
   pendingPermissions: Map<string, IPendingPermission>;
+  /**
+   * Per session, the open sections that change what a session view shows and emit the events
+   * describing it. A view waits until none is open, so it never shows a change without its event.
+   */
+  publications: Map<string, Set<Promise<void>>>;
   scopeQueue: Promise<void>;
   lifecycle: 'active' | 'retiring' | 'fenced' | 'retired';
   fenceInProgress: boolean;
@@ -652,6 +658,12 @@ type TEventDetails = Record<string, unknown> & {
 
 const maxScheduleDebounceMs = 24 * 60 * 60 * 1000;
 const maxBackgroundExecutions = 100;
+/**
+ * Consecutive waits a session view makes for queued writes and open sections to settle. Each wait
+ * ends only when real work finishes, so the bound limits starvation by a session that never stops
+ * changing, not the time one slow save may take.
+ */
+const maxSessionViewPasses = 64;
 const maxSubagentTaskDescriptionBytes = 256;
 const maxSubagentPromptBytes = 64 * 1024;
 const maxSubagentTaskIdBytes = 512;
@@ -1924,6 +1936,75 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  /**
+   * Reads the session's metadata, visible messages and pending permissions in one step, together
+   * with the instance's event sequence they include. It waits until no queued projection or scope
+   * write and no change that emits events for the session is in progress.
+   */
+  public async getSessionView(scopeId: string, sessionId: string): Promise<IFlexSessionView> {
+    const { state } = await this.resolveState(scopeId);
+    let stored = this.requireSession(state, sessionId);
+    for (let pass = 0; ; pass++) {
+      if (pass === maxSessionViewPasses) {
+        throw new FlexHarnessSessionBusyError(
+          sessionId,
+          `kept changing through ${maxSessionViewPasses} consecutive waits for a settled view`,
+        );
+      }
+      const scopeQueue = state.scopeQueue;
+      const projectionQueue = stored.projectionQueue;
+      const publications = [...(state.publications.get(sessionId) ?? [])];
+      await Promise.all([scopeQueue, projectionQueue, ...publications]);
+      this.assertStateAcceptingWork(state);
+      stored = this.requireSession(state, sessionId);
+      if (
+        state.scopeQueue === scopeQueue
+        && stored.projectionQueue === projectionQueue
+        && !state.publications.get(sessionId)?.size
+      ) break;
+    }
+    const run = state.activeRuns.get(sessionId);
+    const messages = this.visibleMessages(stored).map((message) => (
+      run && run.stored === stored && message.messageId === run.assistantMessageId
+        && message.status === 'streaming'
+        ? { ...message, parts: run.callbackParts }
+        : message
+    ));
+    return publicSnapshot({
+      session: stored.session,
+      messages,
+      pendingPermissions: [...state.pendingPermissions.values()]
+        .map((pending) => pending.request)
+        .filter((request) => request.sessionId === sessionId)
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt)),
+      sequence: this.sequence,
+    });
+  }
+
+  /**
+   * Opens a section that changes what a view of the session shows and emits the events that
+   * describe the change. Closing is idempotent; close it once the events are emitted or the
+   * change is rolled back.
+   */
+  private openPublication(state: IStorageState, sessionId: string): () => void {
+    let release!: () => void;
+    const section = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    let sections = state.publications.get(sessionId);
+    if (!sections) {
+      sections = new Set();
+      state.publications.set(sessionId, sections);
+    }
+    sections.add(section);
+    return () => {
+      const current = state.publications.get(sessionId);
+      if (!current?.delete(section)) return;
+      if (current.size === 0) state.publications.delete(sessionId);
+      release();
+    };
+  }
+
   public async getMessages(scopeId: string, sessionId: string): Promise<IFlexMessage[]> {
     const { state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
@@ -3397,12 +3478,17 @@ export class FlexHarness<TScope = unknown> {
             .map((runId) => stored.reversionSegments.find((segment) => segment.runId === runId))
             .find((segment) => segment?.status === 'completed');
           if (!target) throw new FlexHarnessValidationError('Pending reversion has no target candidate.');
-          await this.resumePendingApply(state, stored, scopeId, scope, operationSignal);
-          this.emitEvent(scopeId, stored.session, {
-            type: 'session.history.changed',
-            direction,
-            runId: target.runId,
-          });
+          const closePublication = this.openPublication(state, sessionId);
+          try {
+            await this.resumePendingApply(state, stored, scopeId, scope, operationSignal);
+            this.emitEvent(scopeId, stored.session, {
+              type: 'session.history.changed',
+              direction,
+              runId: target.runId,
+            });
+          } finally {
+            closePublication();
+          }
           return target.runId;
         }
         const unit = this.reversionUnit(stored, direction);
@@ -3442,18 +3528,23 @@ export class FlexHarness<TScope = unknown> {
             appliedRunIds: [],
           };
         }, true);
-        await this.resumePendingApply(
-          state,
-          stored,
-          scopeId,
-          scope,
-          operationSignal,
-        );
-        this.emitEvent(scopeId, stored.session, {
-          type: 'session.history.changed',
-          direction,
-          runId: unit.target.runId,
-        });
+        const closePublication = this.openPublication(state, sessionId);
+        try {
+          await this.resumePendingApply(
+            state,
+            stored,
+            scopeId,
+            scope,
+            operationSignal,
+          );
+          this.emitEvent(scopeId, stored.session, {
+            type: 'session.history.changed',
+            direction,
+            runId: unit.target.runId,
+          });
+        } finally {
+          closePublication();
+        }
         return unit.target.runId;
       },
     );
@@ -4405,123 +4496,130 @@ export class FlexHarness<TScope = unknown> {
     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 {
-      this.assertPromptPromotion(queued, run);
-      await this.acquireDelegatedRunAdmission(queued, run);
-      this.assertPromptPromotion(queued, run);
-      await this.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.withRunCompactorContext(
-        run,
-        () => run.stored.agentSession.beginGeneration(
-          generationPrompt,
-          { generationId: run.runId },
-        ),
-      );
-      this.assertPromptPromotion(queued, run);
-      const reservation = this.createReservation(run, prompt);
-      await this.mutateProjection(run.state, run.stored, () => {
-        run.stored.messages.push(reservation.userMessage, reservation.assistantMessage);
-        if (run.stored.session.agent === undefined) {
-          this.pruneReversionState(run.stored, true);
-          const captureId = this.turnReversionProvider
-            ? this.reversionId('capture', run.state.storageKey, run.sessionId, run.runId)
-            : undefined;
-          const protocolVersion = this.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',
+      try {
+        this.assertPromptPromotion(queued, run);
+        await this.acquireDelegatedRunAdmission(queued, run);
+        this.assertPromptPromotion(queued, run);
+        await this.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.withRunCompactorContext(
+          run,
+          () => run.stored.agentSession.beginGeneration(
+            generationPrompt,
+            { generationId: run.runId },
+          ),
+        );
+        this.assertPromptPromotion(queued, run);
+        const reservation = this.createReservation(run, prompt);
+        closeReservationPublication = this.openPublication(run.state, run.sessionId);
+        await this.mutateProjection(run.state, run.stored, () => {
+          run.stored.messages.push(reservation.userMessage, reservation.assistantMessage);
+          if (run.stored.session.agent === undefined) {
+            this.pruneReversionState(run.stored, true);
+            const captureId = this.turnReversionProvider
+              ? this.reversionId('capture', run.state.storageKey, run.sessionId, run.runId)
+              : undefined;
+            const protocolVersion = this.reversionProviderProtocolVersion() ?? 1;
+            run.stored.reversionSegments.push({
               runId: run.runId,
-              captureId,
-              state: 'preparing',
+              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.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.projectExternalError(run, error, projectionReserved ? 'persistence' : 'agentSession');
+        let cleanupErrors: unknown[] = [];
+        let cleanupFailure: unknown;
+        try {
+          await this.closeRunDelegatedRunAdmission(
+            run,
+            !run.delegatedRunAdmissionOwner?.acquisitionDetached,
+          );
+        } catch (closeError) {
+          cleanupErrors.push(closeError);
         }
-      });
-      projectionReserved = true;
-      run.reservedUserMessage = publicSnapshot(reservation.userMessage);
-      run.reservedAssistantMessage = publicSnapshot(reservation.assistantMessage);
-      this.assertPromptPromotion(queued, run);
-      await this.mutateScope(run.state, () => {
-        if (run.controller.signal.aborted) {
-          throw run.controller.signal.reason ?? new FlexHarnessAbortError();
+        try {
+          cleanupErrors.push(...await this.rollbackAdmission(run, projectionReserved, safeError));
+        } catch (rollbackError) {
+          cleanupFailure = rollbackError;
         }
-        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.');
+        if (cleanupFailure !== undefined && cleanupErrors.length > 0) {
+          cleanupFailure = combineErrors([cleanupFailure, ...cleanupErrors]);
         }
-        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.projectExternalError(run, error, projectionReserved ? 'persistence' : 'agentSession');
-      let cleanupErrors: unknown[] = [];
-      let cleanupFailure: unknown;
-      try {
-        await this.closeRunDelegatedRunAdmission(
-          run,
-          !run.delegatedRunAdmissionOwner?.acquisitionDetached,
-        );
-      } catch (closeError) {
-        cleanupErrors.push(closeError);
-      }
-      try {
-        cleanupErrors.push(...await this.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.fenceNamespace(run.state, run, combined);
-        } catch (fenceError) {
-          cleanupFailure = fenceError;
+        if (run.state.lifecycle === 'fenced' && cleanupFailure === undefined) {
+          const combined = combineErrors([safeError, ...cleanupErrors]);
+          try {
+            await this.fenceNamespace(run.state, run, combined);
+          } catch (fenceError) {
+            cleanupFailure = fenceError;
+          }
         }
+        const rejection = cleanupFailure
+          ?? (cleanupErrors.length > 0 ? combineErrors([safeError, ...cleanupErrors]) : safeError);
+        throw rejection;
       }
-      const rejection = cleanupFailure
-        ?? (cleanupErrors.length > 0 ? combineErrors([safeError, ...cleanupErrors]) : safeError);
-      throw rejection;
-    }
 
-    const runType = run.scheduleKey ? 'run.scheduled' : 'run.started';
-    this.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!]) {
+      const runType = run.scheduleKey ? 'run.scheduled' : 'run.started';
       this.emitEvent(run.scopeId, run.stored.session, {
-        type: 'message.created',
+        type: runType,
         runId: run.runId,
-        messageId: message.messageId,
-        message,
+        messageId: run.userMessageId,
+        session: publicSnapshot(run.stored.session),
       });
+      for (const message of [run.reservedUserMessage!, run.reservedAssistantMessage!]) {
+        this.emitEvent(run.scopeId, run.stored.session, {
+          type: 'message.created',
+          runId: run.runId,
+          messageId: message.messageId,
+          message,
+        });
+      }
+    } finally {
+      closeReservationPublication();
     }
 
     queued.status = run.scheduleKey ? 'scheduled' : 'starting';
@@ -4729,15 +4827,20 @@ export class FlexHarness<TScope = unknown> {
       run.steering.keptInContext = true;
       this.refreshAutomaticArchiveHorizon(run.stored);
       run.phase = 'promoting';
+      const closePublication = this.openPublication(run.state, run.sessionId);
       try {
-        await this.promoteCompletedTerminal(run, terminal);
-      } catch (error) {
-        const projected = this.projectExternalError(run, error, 'persistence');
-        await this.fenceNamespace(run.state, run, projected);
-        throw projected;
+        try {
+          await this.promoteCompletedTerminal(run, terminal);
+        } catch (error) {
+          const projected = this.projectExternalError(run, error, 'persistence');
+          await this.fenceNamespace(run.state, run, projected);
+          throw projected;
+        }
+        this.emitTerminalProjection(run, terminal);
+        this.emitFinalRunEvent(run, terminal.assistantMessage, undefined, false);
+      } finally {
+        closePublication();
       }
-      this.emitTerminalProjection(run, terminal);
-      this.emitFinalRunEvent(run, terminal.assistantMessage, undefined, false);
       await this.drainReversionReleases(
         run.state,
         run.stored,
@@ -4858,16 +4961,21 @@ export class FlexHarness<TScope = unknown> {
       : safeError;
     const terminal = this.buildTerminal(run, publicStatus, undefined, terminalError);
     if (!this.isTombstoned(run)) {
+      const closePublication = this.openPublication(run.state, run.sessionId);
       try {
-        await this.publishFailedTerminal(run, terminal);
-      } catch (persistenceError) {
-        errors.push(this.projectExternalError(run, persistenceError, 'persistence'));
-        const combined = combineErrors(errors);
-        await this.fenceNamespace(run.state, run, combined);
-        throw combined;
+        try {
+          await this.publishFailedTerminal(run, terminal);
+        } catch (persistenceError) {
+          errors.push(this.projectExternalError(run, persistenceError, 'persistence'));
+          const combined = combineErrors(errors);
+          await this.fenceNamespace(run.state, run, combined);
+          throw combined;
+        }
+        this.emitTerminalProjection(run, terminal);
+        this.emitFinalRunEvent(run, terminal.assistantMessage, terminalError, publicStatus === 'cancelled');
+      } finally {
+        closePublication();
       }
-      this.emitTerminalProjection(run, terminal);
-      this.emitFinalRunEvent(run, terminal.assistantMessage, terminalError, publicStatus === 'cancelled');
     }
     await this.drainReversionReleases(
       run.state,
@@ -6561,61 +6669,66 @@ export class FlexHarness<TScope = unknown> {
           parts: [],
         }
       : undefined;
-    await this.mutateProjection(run.state, run.stored, () => {
-      const index = run.stored.messages.findIndex((message) => message.messageId === answeredAssistantId);
-      if (index < 0) throw new Error('The steered run has no projected assistant message.');
-      if (!nextAssistant) {
-        run.stored.messages.splice(index, 0, cloneSerializable(steerMessage));
-        return;
+    const closePublication = this.openPublication(run.state, run.sessionId);
+    try {
+      await this.mutateProjection(run.state, run.stored, () => {
+        const index = run.stored.messages.findIndex((message) => message.messageId === answeredAssistantId);
+        if (index < 0) throw new Error('The steered run has no projected assistant message.');
+        if (!nextAssistant) {
+          run.stored.messages.splice(index, 0, cloneSerializable(steerMessage));
+          return;
+        }
+        completedAssistant = {
+          ...cloneSerializable(run.stored.messages[index]),
+          status: 'completed',
+          completedAt: timestamp,
+          parts: cloneSerializable(run.callbackParts),
+          ...(run.modelResolution ? { model: cloneSerializable(run.modelResolution.identity) } : {}),
+        };
+        run.stored.messages.splice(
+          index,
+          1,
+          cloneSerializable(completedAssistant),
+          cloneSerializable(steerMessage),
+          cloneSerializable(nextAssistant),
+        );
+      });
+      if (completedAssistant && nextAssistant) {
+        run.assistantMessageId = nextAssistant.messageId;
+        run.reservedAssistantMessage = publicSnapshot(nextAssistant);
+        run.callbackParts = [];
+        run.reasoningPartIds.clear();
+        this.emitEvent(run.scopeId, run.stored.session, {
+          type: 'message.updated',
+          runId: run.runId,
+          messageId: completedAssistant.messageId,
+          message: publicSnapshot(completedAssistant),
+        });
       }
-      completedAssistant = {
-        ...cloneSerializable(run.stored.messages[index]),
-        status: 'completed',
-        completedAt: timestamp,
-        parts: cloneSerializable(run.callbackParts),
-        ...(run.modelResolution ? { model: cloneSerializable(run.modelResolution.identity) } : {}),
-      };
-      run.stored.messages.splice(
-        index,
-        1,
-        cloneSerializable(completedAssistant),
-        cloneSerializable(steerMessage),
-        cloneSerializable(nextAssistant),
-      );
-    });
-    if (completedAssistant && nextAssistant) {
-      run.assistantMessageId = nextAssistant.messageId;
-      run.reservedAssistantMessage = publicSnapshot(nextAssistant);
-      run.callbackParts = [];
-      run.reasoningPartIds.clear();
       this.emitEvent(run.scopeId, run.stored.session, {
-        type: 'message.updated',
+        type: 'message.created',
         runId: run.runId,
-        messageId: completedAssistant.messageId,
-        message: publicSnapshot(completedAssistant),
+        messageId: steerMessage.messageId,
+        message: publicSnapshot(steerMessage),
       });
-    }
-    this.emitEvent(run.scopeId, run.stored.session, {
-      type: 'message.created',
-      runId: run.runId,
-      messageId: steerMessage.messageId,
-      message: publicSnapshot(steerMessage),
-    });
-    if (nextAssistant) {
+      if (nextAssistant) {
+        this.emitEvent(run.scopeId, run.stored.session, {
+          type: 'message.created',
+          runId: run.runId,
+          messageId: nextAssistant.messageId,
+          message: publicSnapshot(nextAssistant),
+        });
+      }
       this.emitEvent(run.scopeId, run.stored.session, {
-        type: 'message.created',
+        type: 'prompt.steer.applied',
+        queueId: run.queueId,
         runId: run.runId,
-        messageId: nextAssistant.messageId,
-        message: publicSnapshot(nextAssistant),
+        steerId: applied.inputId,
+        messageId: steerMessage.messageId,
       });
+    } finally {
+      closePublication();
     }
-    this.emitEvent(run.scopeId, run.stored.session, {
-      type: 'prompt.steer.applied',
-      queueId: run.queueId,
-      runId: run.runId,
-      steerId: applied.inputId,
-      messageId: steerMessage.messageId,
-    });
   }
 
   private buildTerminal(
@@ -8255,28 +8368,33 @@ export class FlexHarness<TScope = unknown> {
       responseQueue: Promise.resolve(),
       abortListener,
     };
-    state.pendingPermissions.set(request.permissionId, pending);
-    run.pendingPermissionIds.add(request.permissionId);
-    run.controller.signal.addEventListener('abort', abortListener, { once: true });
+    const closePublication = this.openPublication(state, run.sessionId);
     try {
-      await this.mutateScope(state, () => {
-        if (state.sessions.get(run.sessionId) !== run.stored) {
-          throw new FlexHarnessAbortError('The session was deleted while permission was pending.');
-        }
-        run.stored.session.status = 'waiting_permission';
-        run.stored.session.activity.status = 'waiting_permission';
-        run.stored.session.updatedAt = new Date().toISOString();
-      }, true);
-    } catch (error) {
-      this.forceRejectPending(state, pending, this.projectExternalError(run, error, 'persistence'));
-      return promise;
-    }
-    if (!pending.settled) {
-      this.emitEvent(run.scopeId, run.stored.session, {
-        type: 'permission.requested',
-        runId: run.runId,
-        request: publicSnapshot(request),
-      });
+      state.pendingPermissions.set(request.permissionId, pending);
+      run.pendingPermissionIds.add(request.permissionId);
+      run.controller.signal.addEventListener('abort', abortListener, { once: true });
+      try {
+        await this.mutateScope(state, () => {
+          if (state.sessions.get(run.sessionId) !== run.stored) {
+            throw new FlexHarnessAbortError('The session was deleted while permission was pending.');
+          }
+          run.stored.session.status = 'waiting_permission';
+          run.stored.session.activity.status = 'waiting_permission';
+          run.stored.session.updatedAt = new Date().toISOString();
+        }, true);
+      } catch (error) {
+        this.forceRejectPending(state, pending, this.projectExternalError(run, error, 'persistence'));
+        return promise;
+      }
+      if (!pending.settled) {
+        this.emitEvent(run.scopeId, run.stored.session, {
+          type: 'permission.requested',
+          runId: run.runId,
+          request: publicSnapshot(request),
+        });
+      }
+    } finally {
+      closePublication();
     }
     return promise;
   }
@@ -9085,6 +9203,7 @@ export class FlexHarness<TScope = unknown> {
       activeRuns: new Map(),
       delegatedRunAdmissionOwners: new Set(),
       pendingPermissions: new Map(),
+      publications: new Map(),
       scopeQueue: Promise.resolve(),
       lifecycle: 'active',
       fenceInProgress: false,

package/ts/interfaces.ts

@@ -513,6 +513,25 @@ export interface IFlexMessagePage {
   nextCursor?: string;
 }
 
+/**
+ * A session as the events up to `sequence` describe it, read in one step. Replaying the events of
+ * the same harness instance after `sequence` onto it gives the session's later states.
+ */
+export interface IFlexSessionView {
+  /** Current metadata. Its status can be ahead of `sequence`: status changes emit no event. */
+  session: IFlexSession;
+  /** The visible messages, including what a running turn has streamed so far. */
+  messages: IFlexMessage[];
+  /**
+   * The session's pending permission requests, oldest first. A request its run leaves unanswered,
+   * because the run was stopped or failed, leaves this list without an event of its own; the run's
+   * `run.finished` follows.
+   */
+  pendingPermissions: IFlexPermissionRequest[];
+  /** The `sequence` of the instance's last event this view includes; 0 before the first event. */
+  sequence: number;
+}
+
 export interface IFlexResolvedScope<TScope> {
   storageKey: string;
   scope: TScope;