@modelprofile.com/flexharness 10.17.1 → 10.18.0

package/ts_chat_harness_server/classes.chathub.ts

@@ -0,0 +1,400 @@
+import * as plugins from './plugins.js';
+import { FlexHarnessChatSessionLists } from './classes.sessionlists.js';
+import { FlexHarnessChatSubscription } from './classes.chatsubscription.js';
+import { FlexHarnessChatTurnGate } from './classes.turngate.js';
+import { FlexHarnessChatRequestError, FlexHarnessChatTabUnavailableError } from './errors.js';
+import {
+  BAD_REQUEST_MESSAGE,
+  STOPPED_MESSAGE,
+  isSameTab,
+  readRandomId,
+  tabKey,
+  readSendDetail,
+  readSessionId,
+  readTitle,
+  titleFromMessage,
+} from './functions.validation.js';
+import type {
+  IFlexHarnessChatCaller,
+  IFlexHarnessChatHubOptions,
+  IFlexHarnessChatLimits,
+  IFlexHarnessChatPeers,
+  IFlexHarnessChatTurn,
+  TFlexHarnessChatHubHarness,
+} from './interfaces.js';
+
+type TRequest<TMethod extends keyof plugins.IFlexHarnessChatMethods> = plugins.TFlexHarnessChatRequest<TMethod>;
+type TResponse<TMethod extends keyof plugins.IFlexHarnessChatMethods> = plugins.TFlexHarnessChatResponse<TMethod>;
+
+const NOT_FOUND_MESSAGE = 'This conversation does not exist.';
+const READ_ONLY_MESSAGE = 'This conversation was imported and can only be read. Start a new conversation to continue.';
+const DECISIONS: readonly string[] = ['once', 'always', 'reject'];
+
+export const defaultFlexHarnessChatLimits: Readonly<IFlexHarnessChatLimits> = Object.freeze({
+  turnTimeoutMs: 10 * 60 * 1000,
+  admissionWaitMs: 30 * 1000,
+  toolTimeoutMs: 2 * 60 * 1000,
+  maxPendingDeltas: 2_000,
+  maxMessageChars: 100_000,
+  maxAttachments: 16,
+  maxAttachmentChars: 8 * 1024 * 1024,
+  maxTitleChars: 200,
+  sweepIntervalMs: 5 * 60 * 1000,
+});
+
+/** A conversation as a session list shows it; an imported one says so. */
+export const flexHarnessChatSessionMeta = (sessionArg: plugins.IFlexSession): plugins.IHarnessSessionMeta => ({
+  ...plugins.flexSessionToHarnessMeta(sessionArg),
+  ...(sessionArg.origin?.kind === 'import' ? { statusLabel: 'Imported' } : {}),
+});
+
+/**
+ * Serves `dees-harness-chat` conversations of one FlexHarness to browser tabs, over any transport:
+ * a tab attaches, follows one conversation through numbered updates, sends messages that start or
+ * steer a turn, stops turns, answers permission requests, undoes and redoes turns, and renames and
+ * deletes conversations. A turn runs the tools the host gives it; `runClientTool()` runs one in the
+ * tab that started the turn.
+ *
+ * The host authenticates every request and names its caller: the tab and the scope it may reach. A
+ * session of another scope reads as not found. `stop()` stops the turns the hub started, its
+ * subscriptions and its timers; the harness stays the host's.
+ */
+export class FlexHarnessChatHub<TContext> {
+  private readonly limits: Readonly<IFlexHarnessChatLimits>;
+  private readonly harness: TFlexHarnessChatHubHarness;
+  private readonly peers: IFlexHarnessChatPeers;
+  private readonly readContext: (valueArg: plugins.TJsonValue) => TContext;
+  private readonly titleOf: (sendArg: plugins.IHarnessComposerSendDetail) => string;
+  private readonly gate: FlexHarnessChatTurnGate<TContext>;
+  private readonly sessionLists: FlexHarnessChatSessionLists;
+  private readonly subscriptions = new Map<string, FlexHarnessChatSubscription>();
+  private readonly unsubscribe: () => void;
+  private readonly sweepTimer: ReturnType<typeof setInterval>;
+  /** the requests under way that may start a turn or a subscription; `stop()` waits for them */
+  private readonly requestsUnderWay = new Set<Promise<void>>();
+  /** the sequence of the last harness event the hub received */
+  private lastSequence: number | undefined;
+  private stopped = false;
+
+  constructor(optionsArg: IFlexHarnessChatHubOptions<TContext>) {
+    this.limits = Object.freeze({ ...defaultFlexHarnessChatLimits, ...optionsArg.limits });
+    this.harness = optionsArg.harness;
+    this.peers = optionsArg.peers;
+    this.readContext = optionsArg.readContext;
+    this.titleOf = optionsArg.titleOf ?? titleFromMessage;
+    this.gate = new FlexHarnessChatTurnGate<TContext>(this.harness, this.limits);
+    this.sessionLists = new FlexHarnessChatSessionLists(this.peers, flexHarnessChatSessionMeta);
+    this.unsubscribe = this.harness.subscribe((eventArg) => this.takeEvent(eventArg));
+    this.sweepTimer = setInterval(() => void this.forgetClosedTabs(), this.limits.sweepIntervalMs);
+    this.sweepTimer.unref?.();
+  }
+
+  // ---------------- requests ----------------
+
+  /** Attaches a tab: it follows nothing until it opens a conversation again. */
+  public async attach(callerArg: IFlexHarnessChatCaller): Promise<TResponse<'flexHarnessChatAttach'>> {
+    this.assertRunning();
+    this.closeSubscriptionsOf(callerArg);
+    this.sessionLists.attach(callerArg);
+    const sessions = await this.call(() => this.harness.listSessions(callerArg.scopeId));
+    return {
+      sessions: sessions
+        .filter((session) => !session.parentSessionId)
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+        .map(flexHarnessChatSessionMeta),
+    };
+  }
+
+  public open(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatOpen'>,
+  ): Promise<TResponse<'flexHarnessChatOpen'>> {
+    return this.underWay(() => this.openUnderWay(callerArg, requestArg));
+  }
+
+  private async openUnderWay(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatOpen'>,
+  ): Promise<TResponse<'flexHarnessChatOpen'>> {
+    this.assertRunning();
+    const subscriptionId = readRandomId(requestArg?.subscriptionId);
+    const session = await this.requireSession(callerArg, requestArg.sessionId);
+    this.assertRunning();
+    if (this.subscriptions.has(subscriptionId)) throw new FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
+    this.closeSubscriptionsOf(callerArg);
+    const subscription = new FlexHarnessChatSubscription({
+      id: subscriptionId,
+      tabId: callerArg.tabId,
+      scopeId: callerArg.scopeId,
+      sessionId: session.sessionId,
+      harness: this.harness,
+      peers: this.peers,
+      limits: this.limits,
+      onClosed: (closedArg) => this.forgetSubscription(closedArg),
+    });
+    // subscribed before the session is read: what changes meanwhile is buffered, not lost
+    this.subscriptions.set(subscriptionId, subscription);
+    try {
+      await subscription.load();
+      this.assertRunning();
+    } catch (error) {
+      this.closeSubscription(subscription);
+      throw this.toRequestError(error);
+    }
+    return { session: flexHarnessChatSessionMeta(session), readOnly: session.origin?.kind === 'import' };
+  }
+
+  public async close(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatClose'>,
+  ): Promise<TResponse<'flexHarnessChatClose'>> {
+    const subscription = this.subscriptions.get(requestArg?.subscriptionId);
+    if (subscription && isSameTab(subscription, callerArg)) this.closeSubscription(subscription);
+    return {};
+  }
+
+  public send(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatSend'>,
+  ): Promise<TResponse<'flexHarnessChatSend'>> {
+    // the wait for a turn that is ending counts from here
+    const deadline = Date.now() + this.limits.admissionWaitMs;
+    return this.underWay(() => this.sendUnderWay(callerArg, requestArg, deadline));
+  }
+
+  private async sendUnderWay(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatSend'>,
+    deadlineArg: number,
+  ): Promise<TResponse<'flexHarnessChatSend'>> {
+    this.assertRunning();
+    const send = readSendDetail(requestArg?.send, this.limits);
+    const context = this.readSendContext(requestArg.context);
+    let sessionId: string;
+    let created = false;
+    if (requestArg.sessionId === undefined) {
+      sessionId = (await this.call(() => this.harness.createSession(callerArg.scopeId, { title: this.titleOf(send) }))).sessionId;
+      created = true;
+    } else {
+      const session = await this.requireSession(callerArg, requestArg.sessionId);
+      if (session.origin?.kind === 'import') throw new FlexHarnessChatRequestError(READ_ONLY_MESSAGE);
+      sessionId = session.sessionId;
+    }
+    try {
+      // the hub may have stopped while the conversation was read or created
+      this.assertRunning();
+      return await this.gate.admit(callerArg, sessionId, send, context, deadlineArg);
+    } catch (error) {
+      // a conversation created for this message that never got it is not kept
+      if (created && !(error instanceof plugins.FlexHarnessClosedError)) {
+        await this.harness.deleteSession(callerArg.scopeId, sessionId).catch(() => undefined);
+      }
+      throw this.toRequestError(error);
+    }
+  }
+
+  public async abort(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatAbort'>,
+  ): Promise<TResponse<'flexHarnessChatAbort'>> {
+    const session = await this.requireSession(callerArg, requestArg?.sessionId);
+    await this.call(() => this.harness.abort(callerArg.scopeId, session.sessionId));
+    return {};
+  }
+
+  public async respondToPermission(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatPermission'>,
+  ): Promise<TResponse<'flexHarnessChatPermission'>> {
+    const session = await this.requireSession(callerArg, requestArg?.sessionId);
+    if (typeof requestArg.permissionId !== 'string' || !DECISIONS.includes(requestArg.decision)) {
+      throw new FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
+    }
+    await this.call(() => this.harness.respondToPermission(
+      callerArg.scopeId,
+      session.sessionId,
+      requestArg.permissionId,
+      requestArg.decision,
+    ));
+    return {};
+  }
+
+  public async moveHistory(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatHistory'>,
+  ): Promise<TResponse<'flexHarnessChatHistory'>> {
+    const session = await this.requireSession(callerArg, requestArg?.sessionId);
+    if (requestArg.direction === 'undo') {
+      const result = await this.call(() => this.harness.undoSession(callerArg.scopeId, session.sessionId));
+      return { runId: result.revertedRunId };
+    }
+    if (requestArg.direction === 'redo') {
+      const result = await this.call(() => this.harness.redoSession(callerArg.scopeId, session.sessionId));
+      return { runId: result.restoredRunId };
+    }
+    throw new FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
+  }
+
+  public async renameSession(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatSessionUpdate'>,
+  ): Promise<TResponse<'flexHarnessChatSessionUpdate'>> {
+    const title = readTitle(requestArg?.title, this.limits);
+    const session = await this.requireSession(callerArg, requestArg.sessionId);
+    const updated = await this.call(() => this.harness.updateSession(callerArg.scopeId, session.sessionId, { title }));
+    return { session: flexHarnessChatSessionMeta(updated) };
+  }
+
+  public async deleteSession(
+    callerArg: IFlexHarnessChatCaller,
+    requestArg: TRequest<'flexHarnessChatSessionDelete'>,
+  ): Promise<TResponse<'flexHarnessChatSessionDelete'>> {
+    const session = await this.requireSession(callerArg, requestArg?.sessionId);
+    await this.call(() => this.harness.deleteSession(callerArg.scopeId, session.sessionId));
+    return {};
+  }
+
+  // ---------------- turns ----------------
+
+  /** The running turn of a conversation; the host's model resolver and tool provider read it. */
+  public turnOf(scopeIdArg: string, sessionIdArg: string): IFlexHarnessChatTurn<TContext> | undefined {
+    return this.gate.turnOf(scopeIdArg, sessionIdArg);
+  }
+
+  /**
+   * Runs a tool of the turn in the tab that started it and answers with the tab's output. Fails with
+   * `FlexHarnessChatTabUnavailableError` when the tab is gone or does not answer in time.
+   */
+  public async runClientTool(
+    turnArg: IFlexHarnessChatTurn<TContext>,
+    requestArg: plugins.IFlexHarnessChatToolRequest,
+    optionsArg: { timeoutMs?: number; abortSignal?: AbortSignal } = {},
+  ): Promise<plugins.TJsonValue> {
+    const peer = await this.peers.find({ tabId: turnArg.tabId, scopeId: turnArg.scopeId });
+    if (!peer) throw new FlexHarnessChatTabUnavailableError();
+    try {
+      return await peer.runTool(requestArg, {
+        timeoutMs: optionsArg.timeoutMs ?? this.limits.toolTimeoutMs,
+        ...(optionsArg.abortSignal ? { abortSignal: optionsArg.abortSignal } : {}),
+      });
+    } catch (error) {
+      if (optionsArg.abortSignal?.aborted) throw error;
+      throw new FlexHarnessChatTabUnavailableError({ cause: error });
+    }
+  }
+
+  // ---------------- tabs and lifecycle ----------------
+
+  /** Forgets a tab that is gone: its conversation list and the conversation it followed. */
+  public forgetTab(tabArg: IFlexHarnessChatCaller): void {
+    this.closeSubscriptionsOf(tabArg);
+    this.sessionLists.forget(tabArg);
+  }
+
+  /** Stops the turns the hub started and waits until they ended; clears subscriptions and timers. */
+  public async stop(): Promise<void> {
+    if (this.stopped) return;
+    this.stopped = true;
+    clearInterval(this.sweepTimer);
+    this.unsubscribe();
+    for (const subscription of [...this.subscriptions.values()]) this.closeSubscription(subscription);
+    this.sessionLists.clear();
+    // requests under way refuse at their next step; the gate refuses and cancels what reaches it
+    await Promise.all([this.gate.stop(), ...this.requestsUnderWay]);
+  }
+
+  /** Runs a request that may start a turn or a subscription, so that `stop()` can wait for it. */
+  private underWay<T>(requestArg: () => Promise<T>): Promise<T> {
+    const request = requestArg();
+    const settled = request.then(() => undefined, () => undefined);
+    this.requestsUnderWay.add(settled);
+    void settled.then(() => this.requestsUnderWay.delete(settled));
+    return request;
+  }
+
+  private takeEvent(eventArg: plugins.TFlexHarnessEvent): void {
+    const preceding = this.lastSequence;
+    this.lastSequence = eventArg.sequence;
+    this.gate.takeEvent(eventArg);
+    for (const subscription of this.subscriptions.values()) subscription.takeEvent(eventArg, preceding);
+    if (eventArg.type === 'session.created' || eventArg.type === 'session.updated' || eventArg.type === 'session.deleted') {
+      if (!eventArg.session.parentSessionId) this.sessionLists.publish(eventArg);
+    }
+  }
+
+  /** Forgets the tabs that are gone and run no turn; runs every `sweepIntervalMs` on its own. */
+  private async forgetClosedTabs(): Promise<void> {
+    const tabs = new Map<string, IFlexHarnessChatCaller>();
+    for (const tab of [...this.sessionLists.tabs, ...this.subscriptions.values()]) {
+      tabs.set(tabKey(tab), { tabId: tab.tabId, scopeId: tab.scopeId });
+    }
+    for (const tab of tabs.values()) {
+      if (this.stopped) return;
+      if (this.gate.hasTurnOf(tab)) continue;
+      const peer = await this.peers.find(tab).catch(() => null);
+      if (!peer && !this.gate.hasTurnOf(tab)) this.forgetTab(tab);
+    }
+  }
+
+  private closeSubscriptionsOf(tabArg: IFlexHarnessChatCaller): void {
+    for (const subscription of [...this.subscriptions.values()]) {
+      if (isSameTab(subscription, tabArg)) this.closeSubscription(subscription);
+    }
+  }
+
+  private closeSubscription(subscriptionArg: FlexHarnessChatSubscription): void {
+    subscriptionArg.close();
+    this.forgetSubscription(subscriptionArg);
+  }
+
+  private forgetSubscription(subscriptionArg: FlexHarnessChatSubscription): void {
+    if (this.subscriptions.get(subscriptionArg.id) === subscriptionArg) this.subscriptions.delete(subscriptionArg.id);
+  }
+
+  // ---------------- checks and errors ----------------
+
+  private assertRunning(): void {
+    if (this.stopped) throw new FlexHarnessChatRequestError(STOPPED_MESSAGE);
+  }
+
+  private readSendContext(valueArg: plugins.TJsonValue | undefined): TContext {
+    try {
+      return this.readContext(valueArg ?? null);
+    } catch (error) {
+      if (error instanceof FlexHarnessChatRequestError) throw error;
+      throw new FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
+    }
+  }
+
+  /** A root session of the caller's scope; another scope's session id reads as not found. */
+  private async requireSession(callerArg: IFlexHarnessChatCaller, sessionIdArg: unknown): Promise<plugins.IFlexSession> {
+    const sessionId = readSessionId(sessionIdArg, NOT_FOUND_MESSAGE);
+    let session: plugins.IFlexSession;
+    try {
+      session = await this.harness.getSession(callerArg.scopeId, sessionId);
+    } catch (error) {
+      if (error instanceof plugins.FlexHarnessNotFoundError || error instanceof plugins.FlexHarnessValidationError) {
+        throw new FlexHarnessChatRequestError(NOT_FOUND_MESSAGE);
+      }
+      throw this.toRequestError(error);
+    }
+    if (session.parentSessionId) throw new FlexHarnessChatRequestError(NOT_FOUND_MESSAGE);
+    return session;
+  }
+
+  private async call<T>(fnArg: () => Promise<T>): Promise<T> {
+    try {
+      return await fnArg();
+    } catch (error) {
+      throw this.toRequestError(error);
+    }
+  }
+
+  /** FlexHarness states its refusals for people; anything else stays an internal error. */
+  private toRequestError(errorArg: unknown): unknown {
+    if (errorArg instanceof FlexHarnessChatRequestError) return errorArg;
+    if (errorArg instanceof plugins.FlexHarnessClosedError) return new FlexHarnessChatRequestError(STOPPED_MESSAGE);
+    if (errorArg instanceof plugins.FlexHarnessError) return new FlexHarnessChatRequestError(errorArg.message);
+    return errorArg;
+  }
+}

package/ts_chat_harness_server/classes.chatsubscription.ts

@@ -0,0 +1,257 @@
+import * as plugins from './plugins.js';
+import type { IFlexHarnessChatLimits, IFlexHarnessChatPeers } from './interfaces.js';
+
+type TUpdate = plugins.IFlexHarnessChatUpdate;
+
+/** What a subscription still has to tell its tab. */
+interface IPendingUpdate {
+  reset: boolean;
+  rows: boolean;
+  deltas: plugins.THarnessStreamDelta[];
+  status: boolean;
+  usage: boolean;
+  permissions: boolean;
+  history: boolean;
+  steers: plugins.IFlexHarnessChatSteerOutcome[];
+}
+
+const emptyPending = (): IPendingUpdate => ({
+  reset: false,
+  rows: false,
+  deltas: [],
+  status: false,
+  usage: false,
+  permissions: false,
+  history: false,
+  steers: [],
+});
+
+const hasPending = (pendingArg: IPendingUpdate): boolean =>
+  pendingArg.reset
+  || pendingArg.rows
+  || pendingArg.deltas.length > 0
+  || pendingArg.status
+  || pendingArg.usage
+  || pendingArg.permissions
+  || pendingArg.history
+  || pendingArg.steers.length > 0;
+
+/** The harness reads a subscription makes. */
+export type TFlexHarnessChatSubscriptionHarness = Pick<
+  plugins.FlexHarness<unknown>,
+  'getSessionView' | 'getSessionReversionInfo'
+>;
+
+export interface IFlexHarnessChatSubscriptionOptions {
+  id: string;
+  tabId: string;
+  scopeId: string;
+  sessionId: string;
+  harness: TFlexHarnessChatSubscriptionHarness;
+  peers: IFlexHarnessChatPeers;
+  limits: IFlexHarnessChatLimits;
+  /** called once when the subscription closes itself: its tab is gone or its session unreadable */
+  onClosed: (subscriptionArg: FlexHarnessChatSubscription) => void;
+}
+
+/**
+ * One tab following one conversation. A `FlexHarnessTranscript` takes every event of the harness
+ * instance; what changed reaches the tab as numbered updates, one at a time. A transcript that
+ * loses track, or an update the tab does not acknowledge, makes the next update a `reset`.
+ */
+export class FlexHarnessChatSubscription {
+  public readonly id: string;
+  public readonly tabId: string;
+  public readonly scopeId: string;
+  public readonly sessionId: string;
+
+  private readonly harness: TFlexHarnessChatSubscriptionHarness;
+  private readonly peers: IFlexHarnessChatPeers;
+  private readonly limits: IFlexHarnessChatLimits;
+  private readonly onClosed: (subscriptionArg: FlexHarnessChatSubscription) => void;
+  private readonly transcript: plugins.FlexHarnessTranscript;
+  /** `loading` buffers events until the transcript holds the session's state */
+  private state: 'loading' | 'live' = 'loading';
+  private buffered: Array<{ event: plugins.TFlexHarnessEvent; preceding: number | undefined }> = [];
+  private seq = 0;
+  /** the rows as the tab last received them, as JSON, by id */
+  private sentRows = new Map<string, string>();
+  private pending: IPendingUpdate = emptyPending();
+  private sending = false;
+  private closed = false;
+
+  constructor(optionsArg: IFlexHarnessChatSubscriptionOptions) {
+    this.id = optionsArg.id;
+    this.tabId = optionsArg.tabId;
+    this.scopeId = optionsArg.scopeId;
+    this.sessionId = optionsArg.sessionId;
+    this.harness = optionsArg.harness;
+    this.peers = optionsArg.peers;
+    this.limits = optionsArg.limits;
+    this.onClosed = optionsArg.onClosed;
+    this.transcript = new plugins.FlexHarnessTranscript({ scopeId: this.scopeId, sessionId: this.sessionId });
+  }
+
+  /** Takes one event of the harness instance, in the order the harness emitted them. */
+  public takeEvent(eventArg: plugins.TFlexHarnessEvent, precedingArg: number | undefined): void {
+    if (this.closed) return;
+    if (this.state === 'loading') this.buffered.push({ event: eventArg, preceding: precedingArg });
+    else this.applyEvent(eventArg, precedingArg);
+  }
+
+  /** Reads the session into the transcript, replays what changed meanwhile and sends a reset. */
+  public async load(): Promise<void> {
+    this.state = 'loading';
+    this.buffered = [];
+    const view = await this.harness.getSessionView(this.scopeId, this.sessionId);
+    if (this.closed) return;
+    this.transcript.load({
+      messages: view.messages,
+      permissions: view.pendingPermissions,
+      session: view.session,
+      sequence: view.sequence,
+    });
+    const buffered = this.buffered;
+    this.buffered = [];
+    this.state = 'live';
+    this.pending = { ...emptyPending(), reset: true, steers: this.pending.steers };
+    for (const entry of buffered) {
+      if (this.state !== 'live') {
+        this.buffered.push(entry);
+        continue;
+      }
+      this.applyEvent(entry.event, entry.preceding);
+    }
+    void this.pump();
+  }
+
+  /** Stops following; nothing more reaches the tab. */
+  public close(): void {
+    this.closed = true;
+    this.buffered = [];
+  }
+
+  private applyEvent(eventArg: plugins.TFlexHarnessEvent, precedingArg: number | undefined): void {
+    const change = this.transcript.applyEvent(eventArg, { precedingSequence: precedingArg });
+    if (change.reload) {
+      void this.reload();
+      return;
+    }
+    const pending = this.pending;
+    if (eventArg.scopeId === this.scopeId && eventArg.sessionId === this.sessionId) {
+      if (eventArg.type === 'prompt.steer.applied') {
+        pending.steers.push({ steerId: eventArg.steerId, outcome: 'applied' });
+      } else if (eventArg.type === 'run.finished') {
+        for (const steerId of eventArg.unappliedSteerIds) pending.steers.push({ steerId, outcome: 'unapplied' });
+        pending.history = true;
+      }
+    }
+    if (change.messages) {
+      // the rows are read when the update is sent; they hold every delta up to then
+      pending.rows = true;
+      pending.deltas = [];
+    } else if (change.deltas.length && !pending.rows) {
+      pending.deltas.push(...change.deltas);
+      if (pending.deltas.length > this.limits.maxPendingDeltas) {
+        pending.rows = true;
+        pending.deltas = [];
+      }
+    }
+    if (change.status) pending.status = true;
+    if (change.usage) pending.usage = true;
+    if (change.permissions) pending.permissions = true;
+    if (hasPending(pending)) void this.pump();
+  }
+
+  /** The transcript lost track of the session: read it again; the tab gets a reset. */
+  private async reload(): Promise<void> {
+    if (this.state === 'loading' || this.closed) return;
+    try {
+      await this.load();
+    } catch {
+      // the session is gone or unreadable; the tab sees it in its list and opens another
+      this.closeSelf();
+    }
+  }
+
+  /** Sends what is pending, one update at a time, in seq order. */
+  private async pump(): Promise<void> {
+    if (this.sending) return;
+    this.sending = true;
+    let inFlight: TUpdate | null = null;
+    try {
+      while (!this.closed && this.state === 'live' && hasPending(this.pending)) {
+        const peer = await this.peers.find({ tabId: this.tabId, scopeId: this.scopeId });
+        if (!peer) {
+          this.closeSelf();
+          return;
+        }
+        if (this.closed || this.state !== 'live') return;
+        inFlight = await this.takeUpdate();
+        await peer.update(inFlight);
+        inFlight = null;
+      }
+    } catch {
+      // the tab may have missed an update; it starts over with a reset at the next change
+      this.pending = {
+        ...emptyPending(),
+        reset: true,
+        steers: [...(inFlight?.steers ?? []), ...this.pending.steers],
+      };
+    } finally {
+      this.sending = false;
+    }
+  }
+
+  private async takeUpdate(): Promise<TUpdate> {
+    const pending = this.pending;
+    this.pending = emptyPending();
+    const update: TUpdate = { subscriptionId: this.id, seq: ++this.seq };
+    const reset = pending.reset;
+    const view = reset || pending.rows || pending.status || pending.usage || pending.permissions
+      ? this.transcript.view()
+      : null;
+    if (reset) {
+      update.reset = true;
+      this.sentRows.clear();
+    }
+    if (view && (reset || pending.rows)) {
+      const sent = new Map<string, string>();
+      const upserts: plugins.IHarnessMessage[] = [];
+      for (const row of view.messages) {
+        const json = JSON.stringify(row);
+        if (this.sentRows.get(row.id) !== json) upserts.push(row);
+        sent.set(row.id, json);
+      }
+      this.sentRows = sent;
+      update.rows = { upserts, order: view.messages.map((row) => row.id) };
+    } else if (pending.deltas.length) {
+      update.deltas = pending.deltas;
+    }
+    if (view && (reset || pending.status)) update.status = view.status;
+    if (view && (reset || pending.usage)) update.usage = view.usage;
+    if (view && (reset || pending.permissions)) update.permissions = view.permissions;
+    if (reset || pending.history) {
+      const history = await this.readHistory();
+      if (history) update.history = history;
+    }
+    if (pending.steers.length) update.steers = pending.steers;
+    return update;
+  }
+
+  private async readHistory(): Promise<plugins.IFlexHarnessChatHistoryState | undefined> {
+    try {
+      const info = await this.harness.getSessionReversionInfo(this.scopeId, this.sessionId);
+      return { undoAvailable: info.undoAvailable, redoAvailable: info.redoAvailable };
+    } catch {
+      // the session is being deleted; its next state reaches the tab through the session list
+      return undefined;
+    }
+  }
+
+  private closeSelf(): void {
+    if (this.closed) return;
+    this.close();
+    this.onClosed(this);
+  }
+}