@modelprofile.com/flexharness 13.1.1 → 13.2.0

package/ts/classes.flexharness.cachewarm.ts

@@ -0,0 +1,433 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessNotFoundError,
+  FlexHarnessSessionBusyError,
+  FlexHarnessValidationError,
+  errorToInfo,
+} from './errors.js';
+import type {
+  IFlexCacheWarmInput,
+  IFlexCacheWarmState,
+  IFlexPromptResult,
+  IFlexSession,
+} from './interfaces.js';
+import type {
+  IActiveRun,
+  IQueuedPrompt,
+  IStoredSessionState,
+  IStorageState,
+  TEventDetails,
+} from './interfaces.flexharness.js';
+import type { INormalizedCacheWarmOptions } from './utils.harnessoptions.js';
+import { validateIdentifier } from './utils.validation.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** The prompt of a cache-warm turn. It only has the model read the cached prefix again. */
+export const FLEX_CACHE_WARM_PROMPT =
+  '[cache-warm] This message only keeps the prompt cache warm. No action is needed: do not call '
+  + 'any tool and reply with the single word ok.';
+
+/** The cache TTL assumed when the model call does not report its own. */
+const defaultCacheTtlMs = 5 * 60 * 1000;
+/** How long before the cache expires a warm turn reads it. */
+const cacheWarmMarginMs = 60 * 1000;
+// A stray tool call is refused in the first step and answered in the second.
+const cacheWarmMaxSteps = 2;
+
+interface ISessionCacheWarm {
+  key: string;
+  scopeId: string;
+  sessionId: string;
+  /**
+   * The loaded scope state and session the keeper warms. The keeper never loads a scope: once
+   * these are retired, deleted or replaced, it stops.
+   */
+  state: IStorageState;
+  stored: IStoredSessionState;
+  /** The keeper's stop time, on its clock. */
+  warmUntil: number;
+  /** When the keeper was set, on its clock: the idle baseline before any model call. */
+  setAt: number;
+  deadlineTimer?: unknown;
+  warmTimer?: unknown;
+  nextWarmAt?: number;
+  firing: boolean;
+  /** The session's idle time since its previous model call when the last warm turn was due. */
+  firedAfterIdleMs?: number;
+}
+
+/** The idle time after a model call at which a warm turn reads the cache, from its TTL. */
+export function cacheWarmIdleMs(ttlMs: number | undefined): number {
+  const ttl = ttlMs ?? defaultCacheTtlMs;
+  return Math.max(ttl - cacheWarmMarginMs, Math.floor(ttl / 2));
+}
+
+/** Replaces each tool's `execute` so a cache-warm turn refuses any tool call it makes. */
+export function refuseToolExecution(tools: Record<string, unknown>): void {
+  for (const [name, tool] of Object.entries(tools)) {
+    if (!tool || typeof tool !== 'object' || typeof (tool as { execute?: unknown }).execute !== 'function') continue;
+    tools[name] = {
+      ...tool,
+      execute: async () => {
+        throw new FlexHarnessValidationError('A cache-warm turn runs no tools.');
+      },
+    };
+  }
+}
+
+/** Parses the agent tool's duration: `off`, `0`, or an amount of `s`, `m` or `h`, such as `1h`. */
+export function parseCacheWarmDuration(duration: string): number {
+  const normalized = duration.trim().toLowerCase();
+  if (normalized === 'off' || normalized === '0') return 0;
+  const match = /^(\d{1,6})\s*(s|m|h)$/u.exec(normalized);
+  if (!match) {
+    throw new FlexHarnessValidationError('duration must be "off", "0" or an amount of s, m or h, such as "1h".');
+  }
+  const unitMs = match[2] === 's' ? 1000 : match[2] === 'm' ? 60_000 : 3_600_000;
+  return Number(match[1]) * unitMs;
+}
+
+/**
+ * Keeps a session's prompt cache warm until a deadline. Whenever the session has been idle for
+ * the cache TTL less a minute, it sends a marked cache-warm prompt, whose short turn reads the
+ * cached prefix again and so refreshes it. Process-local: it ends with the harness.
+ */
+export class FlexHarnessCacheWarm<TScope> {
+  private readonly entries = new Map<string, ISessionCacheWarm>();
+
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  private get options(): INormalizedCacheWarmOptions {
+    return this.core.cacheWarmOptions;
+  }
+
+  private key(storageKey: string, sessionId: string): string {
+    return `${storageKey}\u0000${sessionId}`;
+  }
+
+  /** Sets the session's warm deadline to `durationMs` from now, capped; 0 stops the keeper. */
+  public async keepCacheWarm(
+    scopeId: string,
+    sessionId: string,
+    input: IFlexCacheWarmInput,
+  ): Promise<IFlexCacheWarmState> {
+    this.core.assertOpen();
+    validateIdentifier(sessionId, 'sessionId');
+    if (!input || typeof input !== 'object' || !Number.isSafeInteger(input.durationMs) || input.durationMs < 0) {
+      throw new FlexHarnessValidationError('durationMs must be a non-negative integer.');
+    }
+    const { state } = await this.core.resolveState(scopeId);
+    this.core.assertStateAcceptingWork(state);
+    const stored = this.core.requireSession(state, sessionId);
+    return this.set(scopeId, state, stored, input.durationMs, 'host');
+  }
+
+  public async getCacheWarm(scopeId: string, sessionId: string): Promise<IFlexCacheWarmState> {
+    validateIdentifier(sessionId, 'sessionId');
+    const { state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    return this.project(stored, this.entries.get(this.key(state.storageKey, sessionId)));
+  }
+
+  /** The shared setter of the host API and the agent tool. */
+  public set(
+    scopeId: string,
+    state: IStorageState,
+    stored: IStoredSessionState,
+    durationMs: number,
+    source: 'host' | 'agent',
+  ): IFlexCacheWarmState {
+    this.core.assertSessionWritable(stored);
+    if (stored.session.agent !== undefined) {
+      throw new FlexHarnessValidationError('Only a root session keeps its cache warm.');
+    }
+    const key = this.key(state.storageKey, stored.session.sessionId);
+    const existing = this.entries.get(key);
+    if (durationMs === 0) {
+      if (existing) {
+        this.remove(existing);
+        this.emit(scopeId, stored.session, { type: 'cache.warm.changed', source });
+        this.emit(scopeId, stored.session, { type: 'cache.warm.stopped', reason: 'cleared' });
+      }
+      return this.project(stored, undefined);
+    }
+    const now = this.options.clock.now();
+    const entry: ISessionCacheWarm = existing ?? {
+      key,
+      scopeId,
+      sessionId: stored.session.sessionId,
+      state,
+      stored,
+      warmUntil: now,
+      setAt: now,
+      firing: false,
+    };
+    entry.scopeId = scopeId;
+    entry.state = state;
+    entry.stored = stored;
+    entry.warmUntil = now + Math.min(durationMs, this.options.maxDurationMs);
+    this.entries.set(key, entry);
+    if (entry.deadlineTimer !== undefined) this.options.clock.clearTimeout(entry.deadlineTimer);
+    entry.deadlineTimer = this.options.clock.setTimeout(
+      () => this.stopAtDeadline(entry),
+      entry.warmUntil - now,
+    );
+    this.emit(scopeId, stored.session, {
+      type: 'cache.warm.changed',
+      source,
+      warmUntil: new Date(this.toWallTime(entry.warmUntil)).toISOString(),
+    });
+    if (!entry.firing) this.arm(entry, state, stored);
+    return this.project(stored, entry);
+  }
+
+  /** The `keep_cache_warm` built-in tool of a root session. */
+  public createKeepCacheWarmTool(run: IActiveRun): unknown {
+    const maxHours = this.options.maxDurationMs / 3_600_000;
+    return plugins.tool({
+      description: 'Keep this session\'s prompt cache warm while you expect further work, so the next turn '
+        + 'reads the cached context instead of writing it again. While the session is idle, the harness then '
+        + 'sends a short "[cache-warm]" message shortly before the cache would expire. A duration such as '
+        + `"30m" or "1h" sets the deadline to that long from now, at most ${maxHours}h; calling the tool again `
+        + 'replaces the deadline; "off" or "0" stops it.',
+      inputSchema: plugins.z.object({
+        duration: plugins.z.string().min(1).max(32),
+      }).strict(),
+      execute: async ({ duration }: { duration: string }) => {
+        const durationMs = parseCacheWarmDuration(duration);
+        this.core.assertStateAcceptingWork(run.state);
+        if (run.state.sessions.get(run.sessionId) !== run.stored) {
+          throw new FlexHarnessNotFoundError('Session', run.sessionId);
+        }
+        return this.set(run.scopeId, run.state, run.stored, durationMs, 'agent');
+      },
+    });
+  }
+
+  /** A prompt or steer arrived: the session is active, so no warm turn is due. */
+  public onActivity(storageKey: string, sessionId: string): void {
+    const entry = this.entries.get(this.key(storageKey, sessionId));
+    if (entry) this.disarm(entry);
+  }
+
+  /** A root run starts: it is activity, and its model options are what warm turns repeat. */
+  public onRunStarted(run: IActiveRun, queued: IQueuedPrompt): void {
+    if (run.stored.session.agent !== undefined) return;
+    this.onActivity(run.state.storageKey, run.sessionId);
+    if (run.cacheWarm) return;
+    const options = queued.options ?? {};
+    run.stored.cacheWarmPromptOptions = {
+      ...(options.modelHint === undefined ? {} : { modelHint: options.modelHint }),
+      ...(options.system === undefined ? {} : { system: options.system }),
+    };
+  }
+
+  /** A model call of the session was dispatched: the cache's TTL counts from now. */
+  public onModelDispatch(run: IActiveRun, dispatch: plugins.ISmartAiCacheDispatch): void {
+    run.stored.lastCacheDispatch = {
+      at: this.options.clock.now(),
+      idleMs: cacheWarmIdleMs(dispatch.warmDurationMs),
+      ...(dispatch.basis === undefined ? {} : { basis: dispatch.basis }),
+    };
+  }
+
+  /** A prompt of the session finished, whether it ran or not. */
+  public onPromptFinished(
+    queued: IQueuedPrompt,
+    status: 'completed' | 'failed' | 'cancelled',
+    error?: unknown,
+    result?: IFlexPromptResult,
+  ): void {
+    const entry = this.entries.get(this.key(queued.state.storageKey, queued.sessionId));
+    if (queued.cacheWarm && status === 'completed' && result) {
+      const basis = queued.stored.lastCacheDispatch?.basis;
+      this.emit(queued.scopeId, queued.stored.session, {
+        type: 'cache.warm.completed',
+        runId: result.runId,
+        usage: result.usage,
+        ...(entry?.firedAfterIdleMs === undefined ? {} : { idleForMs: entry.firedAfterIdleMs }),
+        ...(basis === undefined ? {} : { basis }),
+      });
+    }
+    if (!entry) return;
+    entry.firing = false;
+    if (queued.cacheWarm && status === 'failed') {
+      this.remove(entry);
+      this.emit(queued.scopeId, queued.stored.session, {
+        type: 'cache.warm.stopped',
+        reason: 'failed',
+        ...(queued.runId === undefined ? {} : { runId: queued.runId }),
+        ...(error === undefined ? {} : { error: errorToInfo(error) }),
+      });
+      return;
+    }
+    if (!this.holdsSession(entry)) return;
+    this.arm(entry, entry.state, entry.stored);
+  }
+
+  /** The scope is being retired: its keepers stop, and none loads the scope again. */
+  public onStateRetiring(state: IStorageState): void {
+    for (const entry of [...this.entries.values()]) {
+      if (entry.state === state) this.stopUnavailable(entry);
+    }
+  }
+
+  /** The sessions were deleted: their keepers stop. */
+  public onSessionsDeleted(state: IStorageState, sessionIds: Iterable<string>): void {
+    for (const sessionId of sessionIds) {
+      const entry = this.entries.get(this.key(state.storageKey, sessionId));
+      if (entry?.state === state) this.stopUnavailable(entry);
+    }
+  }
+
+  public dispose(): void {
+    for (const entry of [...this.entries.values()]) this.remove(entry);
+  }
+
+  private project(stored: IStoredSessionState, entry: ISessionCacheWarm | undefined): IFlexCacheWarmState {
+    return Object.freeze({
+      sessionId: stored.session.sessionId,
+      ...(entry ? { warmUntil: new Date(this.toWallTime(entry.warmUntil)).toISOString() } : {}),
+      ...(entry?.nextWarmAt === undefined
+        ? {}
+        : { nextWarmAt: new Date(this.toWallTime(entry.nextWarmAt)).toISOString() }),
+      ...(entry ? { idleMs: stored.lastCacheDispatch?.idleMs ?? cacheWarmIdleMs(undefined) } : {}),
+      ...(entry && stored.lastCacheDispatch?.basis !== undefined ? { basis: stored.lastCacheDispatch.basis } : {}),
+    });
+  }
+
+  /** Projects a time of the keeper's clock onto the wall clock. */
+  private toWallTime(clockTime: number): number {
+    return Date.now() + (clockTime - this.options.clock.now());
+  }
+
+  private isBusy(state: IStorageState, stored: IStoredSessionState): boolean {
+    return state.activeRuns.has(stored.session.sessionId)
+      || stored.outstandingPromptsById.size > 0
+      || ['running', 'scheduled', 'waiting_permission'].includes(stored.session.status);
+  }
+
+  /**
+   * Whether a warm prompt now would change the session beyond the warm turn: it would end an
+   * undo's redo history, or wait for a reversion or a slash command to settle.
+   */
+  private isHeld(state: IStorageState, stored: IStoredSessionState): boolean {
+    return stored.pendingReversion !== undefined
+      || this.core.reversions.hasHiddenReversionSegments(stored)
+      || this.core.commands.activeSlashCommandExecutions.has(
+        this.core.commands.slashCommandSessionKey(state.storageKey, stored.session.sessionId),
+      );
+  }
+
+  /** Arms the warm timer of an idle session; a busy one arms it again when its run ends. */
+  private arm(entry: ISessionCacheWarm, state: IStorageState, stored: IStoredSessionState): void {
+    this.disarm(entry);
+    if (this.isBusy(state, stored)) return;
+    const mark = stored.lastCacheDispatch;
+    const base = mark?.at ?? entry.setAt;
+    const dueAt = base + (mark?.idleMs ?? cacheWarmIdleMs(undefined));
+    this.armAt(entry, dueAt);
+  }
+
+  private armAt(entry: ISessionCacheWarm, dueAt: number): void {
+    if (dueAt >= entry.warmUntil) return;
+    const now = this.options.clock.now();
+    entry.nextWarmAt = dueAt;
+    entry.warmTimer = this.options.clock.setTimeout(() => {
+      entry.warmTimer = undefined;
+      void this.fire(entry);
+    }, Math.max(0, dueAt - now));
+  }
+
+  private disarm(entry: ISessionCacheWarm): void {
+    if (entry.warmTimer !== undefined) this.options.clock.clearTimeout(entry.warmTimer);
+    entry.warmTimer = undefined;
+    delete entry.nextWarmAt;
+  }
+
+  private remove(entry: ISessionCacheWarm): void {
+    this.disarm(entry);
+    if (entry.deadlineTimer !== undefined) this.options.clock.clearTimeout(entry.deadlineTimer);
+    entry.deadlineTimer = undefined;
+    if (this.entries.get(entry.key) === entry) this.entries.delete(entry.key);
+  }
+
+  /** Whether the keeper's scope state is active and still holds its session. */
+  private holdsSession(entry: ISessionCacheWarm): boolean {
+    return entry.state.lifecycle === 'active'
+      && entry.state.sessions.get(entry.sessionId) === entry.stored
+      && !entry.state.tombstones.has(entry.sessionId);
+  }
+
+  private stopUnavailable(entry: ISessionCacheWarm, error?: unknown): void {
+    if (this.entries.get(entry.key) !== entry) return;
+    entry.firing = false;
+    this.remove(entry);
+    this.emit(entry.scopeId, entry.stored.session, {
+      type: 'cache.warm.stopped',
+      reason: 'unavailable',
+      ...(error === undefined ? {} : { error: errorToInfo(error) }),
+    });
+  }
+
+  private stopAtDeadline(entry: ISessionCacheWarm): void {
+    entry.deadlineTimer = undefined;
+    if (this.entries.get(entry.key) !== entry) return;
+    if (!this.holdsSession(entry)) {
+      this.stopUnavailable(entry);
+      return;
+    }
+    this.remove(entry);
+    this.emit(entry.scopeId, entry.stored.session, { type: 'cache.warm.stopped', reason: 'deadline' });
+  }
+
+  private async fire(entry: ISessionCacheWarm): Promise<void> {
+    delete entry.nextWarmAt;
+    if (this.entries.get(entry.key) !== entry || entry.firing || this.core.closed) return;
+    if (this.options.clock.now() >= entry.warmUntil) {
+      this.stopAtDeadline(entry);
+      return;
+    }
+    if (!this.holdsSession(entry)) {
+      this.stopUnavailable(entry);
+      return;
+    }
+    const { state, stored } = entry;
+    // A busy session arms the timer again when its run ends, through `onPromptFinished`.
+    if (this.isBusy(state, stored)) return;
+    const idleMs = stored.lastCacheDispatch?.idleMs ?? cacheWarmIdleMs(undefined);
+    if (this.isHeld(state, stored)) {
+      this.armAt(entry, this.options.clock.now() + idleMs);
+      return;
+    }
+    entry.firing = true;
+    entry.firedAfterIdleMs = this.options.clock.now() - (stored.lastCacheDispatch?.at ?? entry.setAt);
+    try {
+      await this.core.prompts.enqueuePromptInternal(
+        entry.scopeId,
+        entry.sessionId,
+        FLEX_CACHE_WARM_PROMPT,
+        { ...(stored.cacheWarmPromptOptions ?? {}), maxSteps: cacheWarmMaxSteps },
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        false,
+        true,
+      );
+    } catch (error) {
+      if (this.entries.get(entry.key) !== entry) return;
+      entry.firing = false;
+      if (error instanceof FlexHarnessSessionBusyError) {
+        // Work arrived meanwhile: its run end arms the timer again, as does a later idle check.
+        this.armAt(entry, this.options.clock.now() + idleMs);
+        return;
+      }
+      this.stopUnavailable(entry, error);
+    }
+  }
+
+  private emit(scopeId: string, session: IFlexSession, details: TEventDetails): void {
+    this.core.emitEvent(scopeId, session, details);
+  }
+}

package/ts/classes.flexharness.callbacks.ts

@@ -455,6 +455,7 @@ export class FlexHarnessRunCallbacks<TScope> {
         ...(generationId === undefined ? {} : { runId: generationId }),
         source,
         ...call,
+        ...(run?.cacheWarm ? { cacheWarm: true } : {}),
       });
     } catch (error) {
       // AgentSession isolates the entire callback, including event/context failures. Join it later.

package/ts/classes.flexharness.core.ts

@@ -57,6 +57,7 @@ import {
   normalizeAgentSessionPolicy,
   normalizeAttachmentResolver,
   normalizeBuiltInTools,
+  normalizeCacheWarmOptions,
   normalizeSlashCommands,
   normalizeToolCatalogOptions,
   normalizeSubagents,
@@ -68,6 +69,7 @@ import {
   resolveReversionMaintenanceTimeoutMs,
   resolveReversionLimits,
   type INormalizedBuiltInTools,
+  type INormalizedCacheWarmOptions,
   type TRegisteredSlashCommand,
 } from './utils.harnessoptions.js';
 import {
@@ -119,6 +121,7 @@ import { FlexHarnessSessionDeletion } from './classes.flexharness.deletion.js';
 import { FlexHarnessLifecycle } from './classes.flexharness.lifecycle.js';
 import { FlexHarnessRuns } from './classes.flexharness.runs.js';
 import { FlexHarnessSessions } from './classes.flexharness.sessions.js';
+import { FlexHarnessCacheWarm } from './classes.flexharness.cachewarm.js';
 
 const defaultMaxSubagentDepth = 6;
 const maximumMaxSubagentDepth = 8;
@@ -169,6 +172,7 @@ export class FlexHarnessCore<TScope> {
   private readonly externalErrorProjector?: TFlexExternalErrorProjector;
   public readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
   public readonly builtInTools: INormalizedBuiltInTools;
+  public readonly cacheWarmOptions: INormalizedCacheWarmOptions;
   public readonly toolCatalogOptions: Readonly<IFlexToolCatalogOptions>;
   public readonly slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
   public readonly maxSubagentDepth: number;
@@ -198,6 +202,7 @@ export class FlexHarnessCore<TScope> {
   public readonly lifecycle = new FlexHarnessLifecycle<TScope>(this);
   public readonly runs = new FlexHarnessRuns<TScope>(this);
   public readonly sessions = new FlexHarnessSessions<TScope>(this);
+  public readonly cacheWarm = new FlexHarnessCacheWarm<TScope>(this);
 
   constructor(options: IFlexHarnessOptions<TScope>) {
     if (!options || typeof options !== 'object') {
@@ -243,6 +248,7 @@ export class FlexHarnessCore<TScope> {
     this.externalErrorProjector = options.externalErrorProjector;
     this.subagents = normalizeSubagents(options.subagents);
     this.builtInTools = normalizeBuiltInTools(options.builtInTools);
+    this.cacheWarmOptions = normalizeCacheWarmOptions(options.cacheWarm);
     const toolCatalogOptions = normalizeToolCatalogOptions(options.toolCatalog);
     this.toolCatalogOptions = Object.freeze({
       declarations: toolCatalogOptions.declarations,
@@ -1035,8 +1041,9 @@ export class FlexHarnessCore<TScope> {
         status: latestTerminal.status === 'completed' ? 'idle' : latestTerminal.status,
         completedAt,
         ...terminalActivityError(latestTerminal.assistantMessage),
+        ...(latestTerminal.userMessage.cacheWarm ? { cacheWarm: true as const } : {}),
       };
-      stored.session.updatedAt = completedAt;
+      if (!latestTerminal.userMessage.cacheWarm) stored.session.updatedAt = completedAt;
     } else if (['scheduled', 'running', 'waiting_permission'].includes(stored.session.status)) {
       const timestamp = new Date().toISOString();
       stored.session.status = 'cancelled';

package/ts/classes.flexharness.deletion.ts

@@ -299,6 +299,7 @@ export class FlexHarnessSessionDeletion<TScope> {
     reservation: IReservedSessionDeletion,
   ): Promise<void> {
     const { deletedSessions, descendantRoots } = reservation;
+    this.core.cacheWarm.onSessionsDeleted(state, deletedSessions.map((deleted) => deleted.sessionId));
     const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
     const configurationSettlement = this.core.configurations.abortSessionConfigurations(
       state.storageKey,

package/ts/classes.flexharness.lifecycle.ts

@@ -57,6 +57,7 @@ export class FlexHarnessLifecycle<TScope> {
     this.core.commands.assertNoAmbientSlashCommandTeardown();
     if (this.disposePromise) return this.disposePromise;
     this.core.closed = true;
+    this.core.cacheWarm.dispose();
     let disposal!: Promise<void>;
     disposal = this.disposeInternal().catch((error) => {
       if (this.disposePromise === disposal) this.disposePromise = undefined;
@@ -78,6 +79,7 @@ export class FlexHarnessLifecycle<TScope> {
     }
     state.fenceInProgress = true;
     state.lifecycle = 'fenced';
+    this.core.cacheWarm.onStateRetiring(state);
     const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.'));
     if (!state.compactorLifecycleController.signal.aborted) {
       state.compactorLifecycleController.abort(reason);
@@ -589,6 +591,7 @@ export class FlexHarnessLifecycle<TScope> {
       return;
     }
     if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
+    this.core.cacheWarm.onStateRetiring(state);
     const configurationSettlement = this.core.configurations.abortSessionConfigurations(storageKey, reason);
     if (configurationSettlement) await configurationSettlement;
     for (const staged of [...state.sessionImports.values()]) {

package/ts/classes.flexharness.prompts.ts

@@ -259,8 +259,10 @@ export class FlexHarnessPromptQueue<TScope> {
     prompt: INormalizedFlexPrompt,
     byteSize: number,
   ): IFlexSteerAdmission {
+    // A cache-warm turn runs no tools and caps its output, so it takes in no steer.
     if (
-      run.phase === 'closing'
+      run.cacheWarm
+      || run.phase === 'closing'
       || run.phase === 'finalizing'
       || run.phase === 'promoting'
       || run.callbacksClosed
@@ -323,6 +325,7 @@ export class FlexHarnessPromptQueue<TScope> {
     delegationSeed?: IDelegatedRunAdmissionSeed,
     admissionSignal?: AbortSignal,
     slashCommandAdmission = false,
+    cacheWarm = false,
   ): Promise<{
     admission: IFlexPromptQueueAdmission;
     started: Promise<IFlexPromptAdmission>;
@@ -381,6 +384,9 @@ export class FlexHarnessPromptQueue<TScope> {
       if (stored.pendingReversion) {
         throw new FlexHarnessSessionBusyError(sessionId, 'has a pending reversion operation');
       }
+      if (cacheWarm && (state.activeRuns.has(sessionId) || stored.outstandingPromptsById.size > 0)) {
+        throw new FlexHarnessSessionBusyError(sessionId, 'is active, so it needs no cache-warm turn');
+      }
       if (stored.session.agent !== undefined && delegationSeed === undefined) {
         throw new FlexHarnessValidationError(
           'Subagent sessions can only be prompted through the foreground delegate tool.',
@@ -434,6 +440,7 @@ export class FlexHarnessPromptQueue<TScope> {
         status: 'queued',
         queuedAt: new Date().toISOString(),
         ...(scheduleKey === undefined ? {} : { scheduleKey, debounceMs }),
+        ...(cacheWarm ? { cacheWarm: true as const } : {}),
         prompt: normalizedPrompt,
         options: normalizedOptions,
         ...(delegationSeed === undefined ? {} : { delegationSeed }),
@@ -448,6 +455,7 @@ export class FlexHarnessPromptQueue<TScope> {
       stored.promptQueue.push(queued);
       stored.outstandingPromptsById.set(queued.queueId, queued);
       stored.outstandingPromptBytes += byteSize;
+      if (!cacheWarm) this.core.cacheWarm.onActivity(state.storageKey, sessionId);
       this.emitPromptQueueEvent(queued, 'prompt.queued');
       this.schedulePromptQueueDrain(state, stored);
       return {
@@ -593,7 +601,8 @@ export class FlexHarnessPromptQueue<TScope> {
           }
           run.stored.metrics.pendingGenerationId = run.runId;
           run.stored.messages.push(reservation.userMessage, reservation.assistantMessage);
-          if (run.stored.session.agent === undefined) {
+          // A cache-warm turn is no turn of the user's: it gets no reversion segment of its own.
+          if (run.stored.session.agent === undefined && !run.cacheWarm) {
             this.core.reversions.pruneReversionState(run.stored, true);
             const captureId = this.core.turnReversionProvider
               ? this.core.reversions.reversionId('capture', run.state.storageKey, run.sessionId, run.runId)
@@ -638,10 +647,13 @@ export class FlexHarnessPromptQueue<TScope> {
             runId: run.runId,
             status: run.scheduleKey ? 'scheduled' : 'running',
             startedAt: reservation.userMessage.createdAt,
+            ...(run.cacheWarm ? { cacheWarm: true as const } : {}),
           };
-          run.stored.session.updatedAt = reservation.userMessage.createdAt;
-          const preview = run.stored.session.preview ?? sessionPreview(run.stored.messages);
-          if (preview !== undefined) run.stored.session.preview = preview;
+          if (!run.cacheWarm) {
+            run.stored.session.updatedAt = reservation.userMessage.createdAt;
+            const preview = run.stored.session.preview ?? sessionPreview(run.stored.messages);
+            if (preview !== undefined) run.stored.session.preview = preview;
+          }
         });
       } catch (error) {
         if (containsStoreCommitUncertainty(error)) run.state.lifecycle = 'fenced';
@@ -683,6 +695,7 @@ export class FlexHarnessPromptQueue<TScope> {
         runId: run.runId,
         messageId: run.userMessageId,
         session: publicSnapshot(run.stored.session),
+        ...(run.cacheWarm ? { cacheWarm: true } : {}),
       });
       for (const message of [run.reservedUserMessage!, run.reservedAssistantMessage!]) {
         this.core.emitEvent(run.scopeId, run.stored.session, {
@@ -697,6 +710,7 @@ export class FlexHarnessPromptQueue<TScope> {
     }
 
     queued.status = run.scheduleKey ? 'scheduled' : 'starting';
+    this.core.cacheWarm.onRunStarted(run, queued);
     this.emitPromptQueueEvent(queued, 'prompt.started');
     queued.resolveStarted(Object.freeze({
       queueId: queued.queueId,
@@ -712,7 +726,10 @@ export class FlexHarnessPromptQueue<TScope> {
         this.core.runs.prepareGeneration(run, options, context.abortSignal),
       pendingInput: run.steering.input,
       activateOnBackgroundJobs: true,
-      onCacheDispatch: (dispatch: plugins.ISmartAiCacheDispatch) => { run.cacheDispatch = dispatch; },
+      onCacheDispatch: (dispatch: plugins.ISmartAiCacheDispatch) => {
+        run.cacheDispatch = dispatch;
+        this.core.cacheWarm.onModelDispatch(run, dispatch);
+      },
       onInputApplied: (input: plugins.IAgentAppliedInput) => this.core.runs.applyRunSteer(run, input),
       beforeFinish: (context: { abortSignal: AbortSignal }) =>
         this.core.subagentTasks.awaitNextBackgroundSubagent(run, context.abortSignal),
@@ -745,6 +762,7 @@ export class FlexHarnessPromptQueue<TScope> {
       queuedAt: queued.queuedAt,
       ...(queued.runId ? { runId: queued.runId } : {}),
       ...(queued.scheduleKey ? { scheduleKey: queued.scheduleKey } : {}),
+      ...(queued.cacheWarm ? { cacheWarm: true } : {}),
       ...(queued.startedAt ? { startedAt: queued.startedAt } : {}),
     };
   }
@@ -815,6 +833,7 @@ export class FlexHarnessPromptQueue<TScope> {
       queued.rejectStarted(rejection);
       queued.rejectCompletion(rejection);
     }
+    this.core.cacheWarm.onPromptFinished(queued, status, error, result);
   }
 
   public cancelQueuedPrompt(

package/ts/classes.flexharness.reversions.ts

@@ -961,7 +961,8 @@ export class FlexHarnessReversions<TScope> {
   }
 
   public async prepareRunReversion(run: IActiveRun, signal: AbortSignal): Promise<void> {
-    if (run.stored.session.agent !== undefined || !this.core.turnReversionProvider) return;
+    // A cache-warm turn changes no workspace, so it captures none.
+    if (run.stored.session.agent !== undefined || run.cacheWarm || !this.core.turnReversionProvider) return;
     const segment = run.stored.reversionSegments.find((entry) => entry.runId === run.runId);
     const captureId = segment?.captureId;
     if (!segment || !captureId) {
@@ -1163,6 +1164,11 @@ export class FlexHarnessReversions<TScope> {
     delete segment.workspaceReference;
   }
 
+  /** Whether an undo hid turns that the next prompt would drop with their redo history. */
+  public hasHiddenReversionSegments(stored: IStoredSessionState): boolean {
+    return this.hiddenReversionSegments(stored).length > 0;
+  }
+
   private hiddenReversionSegments(stored: IStoredSessionState): IFlexReversionSegment[] {
     const firstHidden = this.reversionGroups(stored)[stored.revertCursor]?.segments[0];
     if (!firstHidden) return [];