@modelprofile.com/flexharness 13.1.1 → 13.2.1

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,
@@ -963,32 +969,42 @@ export class FlexHarnessCore<TScope> {
       ...stored.messages.map((message) => message.runId),
       ...stored.stagedTerminals.map((terminal) => terminal.runId),
     ]);
+    // The session's state is the latest real turn's: a cache-warm turn's terminal never sets it.
     let latestTerminal: IFlexTerminalProjection | undefined;
     for (const runId of runIds) {
       const outcome = outcomes.get(runId);
       const stage = stages.get(runId);
       if (outcome === 'accepted' && stage?.status === 'completed') {
         this.runs.replaceVisibleRun(stored, stage);
-        latestTerminal = stage;
+        if (!stage.userMessage.cacheWarm) latestTerminal = stage;
       } else if (outcome !== 'accepted') {
         const visible = stored.messages.filter((message) => message.runId === runId);
-        if (visible.length > 0 || stage) {
+        // A run that failed or was stopped keeps its terminal and its error: the staged one, or the
+        // one it published. Only a run that never reached its terminal is repaired as interrupted.
+        const ended = stage && stage.status !== 'completed'
+          ? stage
+          : stage ? undefined : this.publishedTerminal(runId, visible);
+        if (ended) {
+          if (ended === stage) this.runs.replaceVisibleRun(stored, stage);
+          if (!ended.userMessage.cacheWarm) latestTerminal = ended;
+        } else if (visible.length > 0 || stage) {
           const status = outcome === 'rejected' ? 'failed' : 'cancelled';
           const terminal = this.repairTerminal(stored.session.sessionId, runId, visible, stage, status);
           this.runs.replaceVisibleRun(stored, terminal);
-          latestTerminal = terminal;
+          if (!terminal.userMessage.cacheWarm) latestTerminal = terminal;
         }
       } else {
         const visibleSuccess = stored.messages.some((message) =>
           message.runId === runId && message.status === 'completed');
         if (visibleSuccess) {
-          latestTerminal = this.repairTerminal(
+          const terminal = this.repairTerminal(
             stored.session.sessionId,
             runId,
             stored.messages.filter((message) => message.runId === runId),
             undefined,
             'completed',
           );
+          if (!terminal.userMessage.cacheWarm) latestTerminal = terminal;
         }
       }
     }
@@ -1027,12 +1043,18 @@ export class FlexHarnessCore<TScope> {
       }
       await this.reversions.recoverPendingCapture(state, stored, scopeId, scope, outcomes);
     }
+    // FlexHarness 13.2.0 marked a warm turn's activity with `cacheWarm`; no activity carries it now.
+    delete (stored.session.activity as { cacheWarm?: true }).cacheWarm;
     if (latestTerminal) {
       const completedAt = latestTerminal.assistantMessage.completedAt ?? new Date().toISOString();
+      const startedAt = stored.session.activity.runId === latestTerminal.runId
+        ? stored.session.activity.startedAt
+        : undefined;
       stored.session.status = latestTerminal.status === 'completed' ? 'idle' : latestTerminal.status;
       stored.session.activity = {
         runId: latestTerminal.runId,
         status: latestTerminal.status === 'completed' ? 'idle' : latestTerminal.status,
+        ...(startedAt === undefined ? {} : { startedAt }),
         completedAt,
         ...terminalActivityError(latestTerminal.assistantMessage),
       };
@@ -1076,6 +1098,30 @@ export class FlexHarnessCore<TScope> {
     return beforeSession !== JSON.stringify(stored.session);
   }
 
+  /**
+   * The failed or cancelled terminal a run published, read from its projected messages. A run
+   * still running has its prompt or its last assistant message streaming; it has none.
+   */
+  private publishedTerminal(
+    runId: string,
+    visible: IFlexMessage[],
+  ): IFlexTerminalProjection | undefined {
+    if (visible.some((message) => message.status === 'streaming')) return undefined;
+    const userMessage = visible.find((message) => message.role === 'user' && message.steerId === undefined);
+    const assistantMessage = [...visible].reverse().find((message) => message.role === 'assistant');
+    if (!userMessage || !assistantMessage) return undefined;
+    const status = assistantMessage.status;
+    if (status !== 'failed' && status !== 'cancelled') return undefined;
+    return {
+      runId,
+      status,
+      userMessage,
+      assistantMessage,
+      ...(assistantMessage.model ? { model: assistantMessage.model } : {}),
+      ...(assistantMessage.usage ? { usage: assistantMessage.usage } : {}),
+    };
+  }
+
   private repairTerminal(
     sessionId: string,
     runId: string,

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)
@@ -633,6 +642,9 @@ export class FlexHarnessPromptQueue<TScope> {
           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.');
           }
+          // A cache-warm turn leaves the session's status, activity, updatedAt and preview as the
+          // last real turn left them; the active run alone keeps the session busy.
+          if (run.cacheWarm) return;
           run.stored.session.status = run.scheduleKey ? 'scheduled' : 'running';
           run.stored.session.activity = {
             runId: run.runId,
@@ -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 [];

package/ts/classes.flexharness.runs.ts

@@ -27,6 +27,7 @@ import {
   type TFlexMessagePart,
 } from './interfaces.js';
 import { FlexToolCatalog, assertNoCatalogCollisions } from './classes.toolcatalog.js';
+import { refuseToolExecution } from './classes.flexharness.cachewarm.js';
 import { cloneSerializable } from './utils.json.js';
 import type { INormalizedFlexPrompt } from './utils.prompt.js';
 import {
@@ -106,6 +107,7 @@ export class FlexHarnessRuns<TScope> {
       ...(queued.scheduleKey === undefined
         ? {}
         : { scheduleKey: queued.scheduleKey, debounceMs: queued.debounceMs }),
+      ...(queued.cacheWarm ? { cacheWarm: true as const } : {}),
       callbackEventCount: 0,
       callbackOutputBytes: 0,
       callbackParts: [],
@@ -527,6 +529,8 @@ export class FlexHarnessRuns<TScope> {
           run.toolCatalog = admittedCatalog;
           Object.assign(admittedTools, this.core.toolDispatch.createCatalogTools(run, admittedCatalog));
         }
+        // A cache-warm turn offers the same tools, as they are part of the cached prefix, but runs none.
+        if (run.cacheWarm) refuseToolExecution(admittedTools);
         tools = Object.keys(admittedTools).length > 0
           ? this.core.toolDispatch.trackToolCalls(run, wrapToolSet(
               admittedTools as TFlexAgentToolSet,
@@ -569,6 +573,7 @@ export class FlexHarnessRuns<TScope> {
         ...(model!.providerOptions ? { providerOptions: model!.providerOptions } : {}),
         ...(model!.cache === undefined ? {} : { cache: model!.cache }),
         ...(options.maxSteps ?? model!.maxSteps ? { maxSteps: options.maxSteps ?? model!.maxSteps } : {}),
+        ...(run.cacheWarm ? { maxOutputTokens: this.core.cacheWarmOptions.maxOutputTokens } : {}),
         ...(close ? { close } : {}),
       };
     } catch (error) {
@@ -593,6 +598,7 @@ export class FlexHarnessRuns<TScope> {
       names.add('delegate_send');
     }
     if (this.core.builtInTools.renameSession) names.add('rename_session');
+    if (this.core.builtInTools.cacheWarm && run.stored.session.agent === undefined) names.add('keep_cache_warm');
     const projectManagement = this.core.builtInTools.projectManagement;
     if (projectManagement?.task) names.add('task');
     if (projectManagement?.goal) names.add('goal');
@@ -618,6 +624,9 @@ export class FlexHarnessRuns<TScope> {
       tools.delegate_send = this.core.subagentTasks.createSubagentSendTool(run);
     }
     if (this.core.builtInTools.renameSession) tools.rename_session = this.createRenameSessionTool(run);
+    if (this.core.builtInTools.cacheWarm && run.stored.session.agent === undefined) {
+      tools.keep_cache_warm = this.core.cacheWarm.createKeepCacheWarmTool(run);
+    }
     const projectManagement = this.core.builtInTools.projectManagement;
     if (projectManagement?.task) tools.task = this.core.projects.createProjectTaskTool(run);
     if (projectManagement?.goal) tools.goal = this.core.projects.createProjectGoalTool(run);
@@ -685,6 +694,7 @@ export class FlexHarnessRuns<TScope> {
       status: 'streaming',
       createdAt: timestamp,
       parts: this.userMessageParts(prompt),
+      ...(run.cacheWarm ? { cacheWarm: true as const } : {}),
     };
     const assistantMessage: IFlexMessage = {
       messageId: run.assistantMessageId,
@@ -694,6 +704,7 @@ export class FlexHarnessRuns<TScope> {
       status: 'streaming',
       createdAt: timestamp,
       parts: [],
+      ...(run.cacheWarm ? { cacheWarm: true as const } : {}),
     };
     return { userMessage, assistantMessage };
   }
@@ -897,6 +908,10 @@ export class FlexHarnessRuns<TScope> {
         part.completedAt = timestamp;
       }
     }
+    if (run.cacheWarm) {
+      userMessage.cacheWarm = true;
+      assistantMessage.cacheWarm = true;
+    }
     userMessage.status = status;
     userMessage.completedAt = timestamp;
     assistantMessage.status = status;
@@ -950,7 +965,7 @@ export class FlexHarnessRuns<TScope> {
       this.replaceVisibleRun(run.stored, terminal);
       run.stored.stagedTerminals = run.stored.stagedTerminals.filter((entry) => entry.runId !== run.runId);
     }, true);
-    if (!this.core.isTombstoned(run)) {
+    if (!this.core.isTombstoned(run) && !run.cacheWarm) {
       await this.core.mutateScope(run.state, () => {
         if (run.state.sessions.get(run.sessionId) !== run.stored) return;
         const timestamp = terminal.assistantMessage.completedAt!;
@@ -974,6 +989,8 @@ export class FlexHarnessRuns<TScope> {
       this.replaceVisibleRun(run.stored, terminal);
       run.stored.stagedTerminals = run.stored.stagedTerminals.filter((entry) => entry.runId !== run.runId);
     }, true);
+    // A failed cache-warm turn reports through `cache.warm.stopped`; the session keeps its state.
+    if (run.cacheWarm) return;
     await this.core.mutateScope(run.state, () => {
       if (run.state.sessions.get(run.sessionId) !== run.stored) return;
       const timestamp = terminal.assistantMessage.completedAt!;
@@ -1099,6 +1116,7 @@ export class FlexHarnessRuns<TScope> {
       ...(error === undefined ? {} : { error: errorToInfo(error) }),
       keptInContext: steering.keptInContext,
       unappliedSteerIds: [...steering.unappliedSteerIds],
+      ...(run.cacheWarm ? { cacheWarm: true } : {}),
     });
   }
 

package/ts/classes.flexharness.ts

@@ -1,6 +1,8 @@
 import type {
   IFlexBackgroundExecution,
   IFlexBeginSessionImportOptions,
+  IFlexCacheWarmInput,
+  IFlexCacheWarmState,
   IFlexCompactSessionOptions,
   IFlexCreateProjectTaskInput,
   IFlexCreateSessionOptions,
@@ -54,6 +56,7 @@ export {
   createFlexResourceToolNamespace,
   createFlexResourceToolName,
 } from './utils.flexharness.js';
+export { FLEX_CACHE_WARM_PROMPT } from './classes.flexharness.cachewarm.js';
 
 export class FlexHarness<TScope = unknown> {
   private readonly core: FlexHarnessCore<TScope>;
@@ -384,6 +387,24 @@ export class FlexHarness<TScope = unknown> {
     return this.core.prompts.steerPrompt(scopeId, sessionId, queueId, steer);
   }
 
+  /**
+   * Keeps the prompt cache of a root session warm until `durationMs` from now, capped at
+   * `cacheWarm.maxDurationMs`; a further call replaces the deadline and `0` stops it. While the
+   * session is idle, a marked cache-warm prompt reads the cached prefix again shortly before it
+   * would expire. The `keep_cache_warm` built-in tool gives the agent the same control.
+   */
+  public keepCacheWarm(
+    scopeId: string,
+    sessionId: string,
+    input: IFlexCacheWarmInput,
+  ): Promise<IFlexCacheWarmState> {
+    return this.core.cacheWarm.keepCacheWarm(scopeId, sessionId, input);
+  }
+
+  public getCacheWarm(scopeId: string, sessionId: string): Promise<IFlexCacheWarmState> {
+    return this.core.cacheWarm.getCacheWarm(scopeId, sessionId);
+  }
+
   /** Sends follow-up input only to an exact running direct child owned by this parent run. */
   public sendSubagentInput(
     scopeId: string,

package/ts/interfaces.flexharness.ts

@@ -102,6 +102,18 @@ export interface IStoredSessionState {
   terminalPromptQueueEntries: Map<string, IFlexPromptQueueEntry>;
   outstandingPromptBytes: number;
   promptQueueDrain?: Promise<void>;
+  /** The last model call of the session in this process, on the cache keeper's clock. */
+  lastCacheDispatch?: ICacheDispatchMark;
+  /** What the last root prompt asked of the model, which its cache-warm turns repeat. */
+  cacheWarmPromptOptions?: Pick<IFlexPromptOptions, 'modelHint' | 'system'>;
+}
+
+export interface ICacheDispatchMark {
+  at: number;
+  /** How long after `at` a cache-warm turn is due: the cache's TTL less a minute. */
+  idleMs: number;
+  /** What the TTL rests on; absent for the five-minute default. */
+  basis?: plugins.TSmartAiCacheBudgetBasis;
 }
 
 export interface IRetainedSessionCleanup {
@@ -220,6 +232,8 @@ export interface IActiveRun {
   transaction?: plugins.IAgentGenerationHandle;
   scheduleKey?: string;
   debounceMs?: number;
+  /** A cache-warm turn of the session's cache keeper; see `keepCacheWarm()`. */
+  cacheWarm?: true;
   ownerCancellation?: FlexHarnessAbortError;
   internalFailure?: unknown;
   callbackError?: unknown;
@@ -389,6 +403,8 @@ export interface IQueuedPrompt {
   runId?: string;
   scheduleKey?: string;
   debounceMs?: number;
+  /** A cache-warm prompt of the session's cache keeper; see `keepCacheWarm()`. */
+  cacheWarm?: true;
   startedAt?: string;
   prompt?: INormalizedFlexPrompt;
   options?: IFlexPromptOptions;

package/ts/interfaces.ts

@@ -222,6 +222,11 @@ export interface IFlexMessage {
   rejectedPermissionId?: string;
   /** On a user message that steered its running run: the caller's steer identity. */
   steerId?: string;
+  /**
+   * On both messages of a cache-warm turn: the harness sent the prompt only to keep the model's
+   * prompt cache warm. Hosts leave these out of what they show and report as work.
+   */
+  cacheWarm?: true;
 }
 
 export interface IFlexSessionActivity {
@@ -523,6 +528,8 @@ export interface IFlexPromptQueueEntry {
   queuedAt: string;
   runId?: string;
   scheduleKey?: string;
+  /** The entry is a cache-warm prompt; see {@link IFlexMessage.cacheWarm}. */
+  cacheWarm?: true;
   startedAt?: string;
   finishedAt?: string;
   error?: IFlexErrorInfo;
@@ -1897,8 +1904,50 @@ export interface IFlexProjectManagementBuiltInToolsOptions {
 export interface IFlexBuiltInToolsOptions {
   renameSession?: boolean;
   projectManagement?: IFlexProjectManagementBuiltInToolsOptions;
+  /** The `keep_cache_warm` tool of root sessions; see `FlexHarness.keepCacheWarm()`. */
+  cacheWarm?: boolean;
+}
+
+/** The clock the cache keeper reads and sets its timers on. Tests pass a fake one. */
+export interface IFlexCacheWarmClock {
+  now(): number;
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export interface IFlexCacheWarmOptions {
+  /** The longest warm period one call sets, in milliseconds. Defaults to 4 hours. */
+  maxDurationMs?: number;
+  /** Caps the output tokens of each model call of a cache-warm turn. Defaults to 1024. */
+  maxOutputTokens?: number;
+  clock?: IFlexCacheWarmClock;
+}
+
+/** What `keepCacheWarm()` sets. */
+export interface IFlexCacheWarmInput {
+  /** How long from now to keep the cache warm, in milliseconds; 0 stops. Capped at the maximum. */
+  durationMs: number;
 }
 
+/** A session's cache keeper. Process-local: it ends with the harness. */
+export interface IFlexCacheWarmState {
+  sessionId: string;
+  /** Present while the keeper runs: when it stops, as an ISO timestamp. */
+  warmUntil?: string;
+  /** Present while a warm turn is due: when, as an ISO timestamp. */
+  nextWarmAt?: string;
+  /** The idle time after a model call at which a warm turn is due, in milliseconds. */
+  idleMs?: number;
+  /**
+   * What `idleMs` rests on, from the last model call: the observed cache lifetime of its provider,
+   * model and endpoint (see `TSmartAiCacheBudgetBasis` of `@modelprofile.com/flexharness-models`).
+   * Absent while no call was observed, when the five-minute default applies.
+   */
+  basis?: TFlexCacheWarmBasis;
+}
+
+export type TFlexCacheWarmBasis = plugins.TSmartAiCacheBudgetBasis;
+
 /** What an attachment resolver is asked for: the attachment `url` names, for one session. */
 export interface IFlexAttachmentRequest<TScope = unknown> extends IFlexAgentContextInvocation<TScope> {
   readonly url: URL;
@@ -1955,6 +2004,8 @@ export interface IFlexHarnessOptions<TScope> {
   /** Maximum child depth (root is 0). Defaults to 6; configurable from 1 through 8. */
   maxSubagentDepth?: number;
   maxSubagentCallsPerRun?: number;
+  /** Bounds and the clock of the cache keeper; see `keepCacheWarm()`. */
+  cacheWarm?: IFlexCacheWarmOptions;
 }
 
 export interface IFlexUncertainToolExecution {
@@ -2021,6 +2072,8 @@ export interface IFlexRunStartedEvent extends IFlexEventBase {
   readonly runId: string;
   readonly messageId: string;
   readonly session: IFlexSession;
+  /** The run is a cache-warm turn; see {@link IFlexMessage.cacheWarm}. */
+  readonly cacheWarm?: true;
 }
 
 export interface IFlexMessageChangedEvent extends IFlexEventBase {
@@ -2099,6 +2152,8 @@ export interface IFlexRunFinishedEvent extends IFlexEventBase {
    * steer it accepted.
    */
   readonly unappliedSteerIds: readonly string[];
+  /** The run is a cache-warm turn; see {@link IFlexMessage.cacheWarm}. */
+  readonly cacheWarm?: true;
 }
 
 /** The running run accepted a steer; it is taken in at the run's next step boundary. */
@@ -2138,6 +2193,8 @@ export type TFlexModelUsageEvent = IFlexEventBase & {
   readonly type: 'model.usage';
   readonly runId?: string;
   readonly source: 'generation' | 'compaction';
+  /** The call belongs to a cache-warm turn; see {@link IFlexMessage.cacheWarm}. */
+  readonly cacheWarm?: true;
 } & Readonly<TFlexObservedModelCallUsage>;
 
 export interface IFlexPromptQueueEvent extends IFlexEventBase {
@@ -2153,6 +2210,43 @@ export interface IFlexSessionHistoryChangedEvent extends IFlexEventBase {
   readonly runId?: string;
 }
 
+/**
+ * The session's cache keeper changed: `warmUntil` is when it stops, absent once it stopped.
+ * `source` is who set it: the host through `keepCacheWarm()` or the agent through its tool.
+ */
+export interface IFlexCacheWarmChangedEvent extends IFlexEventBase {
+  readonly type: 'cache.warm.changed';
+  readonly source: 'host' | 'agent';
+  readonly warmUntil?: string;
+}
+
+/** A cache-warm turn completed; `usage` shows whether it read the cached prefix. */
+export interface IFlexCacheWarmCompletedEvent extends IFlexEventBase {
+  readonly type: 'cache.warm.completed';
+  readonly runId: string;
+  /**
+   * The turn's usage. `cacheReadTokens` and `cacheWriteTokens` are the provider's own counts:
+   * OpenAI's `input_tokens_details.cached_tokens` and `cache_write_tokens`, Anthropic's
+   * `cache_read_input_tokens` and `cache_creation_input_tokens`.
+   */
+  readonly usage: IFlexUsage;
+  /** How long the session had been idle since its previous model call when the turn was due. */
+  readonly idleForMs?: number;
+  /** What the keeper's timing rested on; see {@link IFlexCacheWarmState.basis}. */
+  readonly basis?: TFlexCacheWarmBasis;
+}
+
+/**
+ * The session's cache keeper stopped: its deadline passed, the host or agent cleared it, a warm
+ * turn failed, or the session can no longer be warmed.
+ */
+export interface IFlexCacheWarmStoppedEvent extends IFlexEventBase {
+  readonly type: 'cache.warm.stopped';
+  readonly reason: 'deadline' | 'cleared' | 'failed' | 'unavailable';
+  readonly runId?: string;
+  readonly error?: IFlexErrorInfo;
+}
+
 export interface IFlexErrorInfo {
   name: string;
   message: string;
@@ -2178,6 +2272,9 @@ export type TFlexHarnessEvent =
   | IFlexPromptQueueEvent
   | IFlexSteerAcceptedEvent
   | IFlexSteerAppliedEvent
-  | IFlexSessionHistoryChangedEvent;
+  | IFlexSessionHistoryChangedEvent
+  | IFlexCacheWarmChangedEvent
+  | IFlexCacheWarmCompletedEvent
+  | IFlexCacheWarmStoppedEvent;
 
 export type TFlexHarnessEventListener = (event: TFlexHarnessEvent) => void;

package/ts/plugins.ts

@@ -138,6 +138,7 @@ export type {
   IAgentAppliedInput,
   IAgentResolvedAttachment,
   ISmartAiCacheDispatch,
+  TSmartAiCacheBudgetBasis,
   IAgentEventArchive,
   IAgentEventChange,
   IAgentContextCompactionOptions,