@modelprofile.com/flexharness 13.1.1 → 13.2.0

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;
@@ -960,8 +975,9 @@ export class FlexHarnessRuns<TScope> {
           status: 'idle',
           startedAt: run.stored.session.activity.startedAt,
           completedAt: timestamp,
+          ...(run.cacheWarm ? { cacheWarm: true as const } : {}),
         };
-        run.stored.session.updatedAt = timestamp;
+        if (!run.cacheWarm) run.stored.session.updatedAt = timestamp;
       }, true);
     }
   }
@@ -985,8 +1001,9 @@ export class FlexHarnessRuns<TScope> {
         startedAt: run.stored.session.activity.startedAt,
         completedAt: timestamp,
         ...terminalActivityError(terminal.assistantMessage),
+        ...(run.cacheWarm ? { cacheWarm: true as const } : {}),
       };
-      run.stored.session.updatedAt = timestamp;
+      if (!run.cacheWarm) run.stored.session.updatedAt = timestamp;
     }, true);
   }
 
@@ -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 {
@@ -234,6 +239,8 @@ export interface IFlexSessionActivity {
   limit?: TFlexModelLimit;
   /** The permission whose rejection stopped the last run, next to its error. */
   rejectedPermissionId?: string;
+  /** The run is or was a cache-warm turn; see {@link IFlexMessage.cacheWarm}. */
+  cacheWarm?: true;
 }
 
 export interface IFlexSession {
@@ -523,6 +530,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 +1906,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 +2006,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 +2074,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 +2154,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 +2195,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 +2212,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 +2274,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,

package/ts/readme.md

@@ -418,6 +418,7 @@ The tools use strict action-discriminated inputs:
 - `goal`: `get`, `set`, or `clear`.
 - `scratchpad`: `get`, `set`, `append`, or `clear`. Append concatenates the supplied content exactly.
 - `rename_session`: sets the active session title and returns the authoritative session.
+- `keep_cache_warm` (`cacheWarm: true`, root sessions only): keeps the session's prompt cache warm; see [Keeping the Prompt Cache Warm](#keeping-the-prompt-cache-warm).
 
 Every project action returns the authoritative revision and state; task mutations also return the affected task, and clear returns the removed tasks. Reads never save. A set, clear, append, update, idempotent create, or empty task clear that makes no state change returns the current revision without writing. Mutations load once, apply once, validate the complete next snapshot, and issue one compare-and-swap save at `revision + 1`. FlexHarness never retries or merges an external conflict.
 
@@ -729,6 +730,32 @@ The run takes a steer in at its next step boundary: after the tool results of it
 
 `steerPrompt()` resolves with `{ steerId, queueId, runId }` once the run accepted the steer and `prompt.steer.accepted` was emitted; `prompt.steer.applied` carries the `messageId` of the user message the steer became. Every accepted steer ends in exactly one of two ways: it is in the model context of later turns, or it is listed in `unappliedSteerIds`, in arrival order, on `IFlexPromptResult` and `run.finished`, and on the finished queue entry when that list is not empty. A steer is listed when the run did not take it in before it ended, because its last model step was already running or because it was stopped or failed, and also when the run itself does not stay in context. `keptInContext` on `run.finished` and on the finished queue entry says whether it does: it is `false` for a failed run and for a run stopped before any model output, and such a run lists every steer it accepted, including the ones it took in and reported with `prompt.steer.applied`. Send its prompt and its unapplied steers again to have them answered. The run stops taking steers atomically when its generation ends or `abort()`/`cancelPrompt()` stops it. A steer for a prompt without a running run, or whose run is ending, is refused with `FlexHarnessSteerRejectedError` reason `not-running`; the caller sends it as the next turn instead. Reusing a `steerId` within a run is refused with reason `duplicate`, an unknown `queueId` throws `FlexHarnessNotFoundError`, and child sessions reject this general API (their exact parent run uses `sendSubagentInput()` or `delegate_send` instead). A run holds at most `maxOutstandingPromptsPerSession` pending steers, and their bytes count against the session's outstanding prompt byte limit until the run takes them in or ends, so `startPrompt()` and `enqueuePrompt()` are refused with `FlexHarnessQueueFullError` while pending steers fill it. They are process-local like queue entries: a process restart ends the run and drops its pending steers, while steers it took in are durable parts of the turn.
 
+### Keeping the Prompt Cache Warm
+
+A provider's prompt cache expires when nothing reads it for its TTL, and the next turn then writes the whole prefix again. `keepCacheWarm()` keeps a root session's cache warm until a deadline:
+
+```typescript
+await harness.keepCacheWarm(scopeId, sessionId, { durationMs: 60 * 60 * 1000 }); // warm until 1 h from now
+await harness.keepCacheWarm(scopeId, sessionId, { durationMs: 0 }); // stop
+const state = await harness.getCacheWarm(scopeId, sessionId); // { sessionId, warmUntil?, nextWarmAt?, idleMs?, basis? }
+```
+
+Each call replaces the deadline with `durationMs` from now, capped at `cacheWarm.maxDurationMs` (default 4 h, at most 24 h); `0` stops it. While the deadline has not passed and the session is idle, the harness sends a cache-warm prompt once the session has had no model call for the cache TTL less one minute: 4 minutes for a 5-minute cache, 29 for a 30-minute one, 59 for a 1-hour one. The TTL comes from the request the provider actually sent last, its `basis` in `getCacheWarm()`:
+
+| `basis` | TTL | Sent request |
+| --- | --- | --- |
+| `anthropic-5m`, `anthropic-1h` | 5 min, 1 h | Anthropic: the shortest `cache_control` lifetime of the request |
+| `openai-30m` | 30 min | OpenAI's API, GPT-5.6 and later: `prompt_cache_options.ttl` is 30 minutes after the last write or reuse |
+| `openai-24h` | 30 min | OpenAI's API, an earlier model with `prompt_cache_retention: '24h'` (`cache: { retention: '24h' }`): OpenAI keeps the prefix typically around 30 minutes and up to 24 hours, without promising more |
+| `openai-in-memory` | 5 min | OpenAI's API, an earlier model with `in_memory` or no retention; or the ChatGPT backend of ChatGPT accounts, which takes no retention and documents none. In-memory entries last 5 to 10 minutes of inactivity |
+| `configured` | `cache.warmDurationMs` | any |
+
+With no basis (another provider or endpoint, or a custom transport that may change the request) the TTL is 5 minutes. No OpenAI retention promises a hit beyond about 30 minutes, so none makes warming unnecessary; extended retention only spaces warm turns further apart. Source: OpenAI's [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching), read 2026-10-11. A prompt, a steer or a running turn resets the wait, and no warm prompt is sent while a turn runs, a prompt is queued, an undo's redo history is open, a reversion is pending or a slash command runs. The warm prompt is the fixed text `FLEX_CACHE_WARM_PROMPT`, starting with `[cache-warm]`, which asks for the single word `ok`. Its turn uses the model and system of the session's last turn and offers the same tools, so it reads the cached prefix, but it refuses every tool call, takes at most two steps, caps each model call at `cacheWarm.maxOutputTokens` (default 1024) and takes no steer: `steerPrompt()` refuses one with reason `not-running`. Keeping a session warm costs a cache read of its prefix and a few new tokens per warm turn; the warm exchanges stay in the model context.
+
+Warm turns are marked so hosts can leave them out of what they show and of what they count as work: both messages, the session `activity`, the prompt queue entry, `run.started`, `run.finished` and `model.usage` carry `cacheWarm: true`. A warm turn changes neither the session's `updatedAt` nor its `preview`, and adds no undo step. Three events report the keeper: `cache.warm.changed` (`source` `host` or `agent`, `warmUntil` absent once stopped), `cache.warm.completed` with the warm turn's `usage`, whose `cacheReadTokens` and `cacheWriteTokens` are the provider's own counts and show whether it hit the cache (OpenAI's `input_tokens_details.cached_tokens` and `cache_write_tokens`, Anthropic's `cache_read_input_tokens` and `cache_creation_input_tokens`), its `idleForMs` since the session's previous model call and its `basis`, and `cache.warm.stopped` with `reason` `deadline`, `cleared`, `failed` (the warm turn failed; `error` set) or `unavailable` (the session or its scope went away).
+
+`builtInTools: { cacheWarm: true }` gives root sessions the `keep_cache_warm` tool, so the agent can keep its own cache warm: `{ duration: '1h' }` sets the deadline (amounts of `s`, `m` or `h`), `'off'` or `'0'` stops it. The keeper is process-local: it ends with `dispose()` and does not survive a restart. It warms only the loaded scope it was set in: retiring the scope or deleting the session stops it with `unavailable`, and it never loads a scope again. Tests pass `cacheWarm.clock` (`now`, `setTimeout`, `clearTimeout`) to drive it with a fake clock.
+
 ## Slash Commands
 
 `parseSlashCommand()` is the public strict pure parser. It accepts at most 768 KiB, returns `not-command` for input not starting with `/`, `malformed` for invalid slash syntax, and `parsed` with the exact input, lowercase command name, separator-stripped raw argument text, and OpenCode-compatible quoted tokenization. Command names match `[a-z][a-z0-9_-]{0,63}`. The public `isValidSlashCommandName(name)` and `isReservedSlashCommandName(name)` helpers let applications validate registration names against the same rules. Single and double quotes group tokens and are stripped; escapes are not interpreted.

package/ts/utils.harnessoptions.ts

@@ -12,6 +12,8 @@ import {
 import type {
   IFlexAgentSessionPolicy,
   IFlexAttachmentResolver,
+  IFlexCacheWarmClock,
+  IFlexCacheWarmOptions,
   IFlexCallbackLimits,
   IFlexHarnessOptions,
   IFlexHarnessStores,
@@ -46,8 +48,21 @@ export interface INormalizedProjectManagementTools {
 export interface INormalizedBuiltInTools {
   readonly renameSession: boolean;
   readonly projectManagement?: INormalizedProjectManagementTools;
+  readonly cacheWarm: boolean;
 }
 
+export interface INormalizedCacheWarmOptions {
+  readonly maxDurationMs: number;
+  readonly maxOutputTokens: number;
+  readonly clock: IFlexCacheWarmClock;
+}
+
+const defaultCacheWarmMaxDurationMs = 4 * 60 * 60 * 1000;
+// One call warms for at most a day; a host extends it by calling again.
+const maximumCacheWarmMaxDurationMs = 24 * 60 * 60 * 1000;
+const defaultCacheWarmMaxOutputTokens = 1024;
+const maximumCacheWarmMaxOutputTokens = 32_768;
+
 const DEFAULT_CALLBACK_LIMITS: Required<IFlexCallbackLimits> = {
   maxEvents: 10_000,
   maxOutputBytes: 1024 * 1024,
@@ -242,7 +257,7 @@ function normalizeCodeModeLimits(codeMode: unknown): Readonly<IFlexCodeModeLimit
 export function normalizeBuiltInTools(
   options: IFlexHarnessOptions<unknown>['builtInTools'],
 ): INormalizedBuiltInTools {
-  if (options === undefined) return Object.freeze({ renameSession: false });
+  if (options === undefined) return Object.freeze({ renameSession: false, cacheWarm: false });
   if (
     !options
     || typeof options !== 'object'
@@ -252,14 +267,19 @@ export function normalizeBuiltInTools(
     throw new FlexHarnessValidationError('builtInTools must be a plain object.');
   }
   const unsupported = Object.keys(options)
-    .find((key) => !['renameSession', 'projectManagement'].includes(key));
+    .find((key) => !['renameSession', 'projectManagement', 'cacheWarm'].includes(key));
   if (unsupported) throw new FlexHarnessValidationError(`builtInTools does not support "${unsupported}".`);
-  if (options.renameSession !== undefined && typeof options.renameSession !== 'boolean') {
-    throw new FlexHarnessValidationError('builtInTools.renameSession must be a boolean.');
+  for (const key of ['renameSession', 'cacheWarm'] as const) {
+    if (options[key] !== undefined && typeof options[key] !== 'boolean') {
+      throw new FlexHarnessValidationError(`builtInTools.${key} must be a boolean.`);
+    }
   }
   const projectManagement = options.projectManagement;
   if (projectManagement === undefined) {
-    return Object.freeze({ renameSession: options.renameSession ?? false });
+    return Object.freeze({
+      renameSession: options.renameSession ?? false,
+      cacheWarm: options.cacheWarm ?? false,
+    });
   }
   if (
     !projectManagement
@@ -283,6 +303,7 @@ export function normalizeBuiltInTools(
   }
   return Object.freeze({
     renameSession: options.renameSession ?? false,
+    cacheWarm: options.cacheWarm ?? false,
     projectManagement: Object.freeze({
       task: projectManagement.task ?? true,
       goal: projectManagement.goal ?? true,
@@ -374,6 +395,54 @@ export function normalizeSlashCommands<TScope>(
   return Object.freeze(normalized);
 }
 
+const systemCacheWarmClock: IFlexCacheWarmClock = Object.freeze({
+  now: () => Date.now(),
+  setTimeout: (callback: () => void, delayMs: number) => {
+    const handle = setTimeout(callback, delayMs);
+    // A warm period never holds the process open.
+    handle.unref?.();
+    return handle;
+  },
+  clearTimeout: (handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+});
+
+export function normalizeCacheWarmOptions(
+  input: IFlexHarnessOptions<unknown>['cacheWarm'],
+): INormalizedCacheWarmOptions {
+  if (input !== undefined && !isPlainOptions(input as unknown)) {
+    throw new FlexHarnessValidationError('cacheWarm must be a plain object.');
+  }
+  const options: IFlexCacheWarmOptions = input ?? {};
+  const unsupported = Object.keys(options)
+    .find((key) => !['maxDurationMs', 'maxOutputTokens', 'clock'].includes(key));
+  if (unsupported) throw new FlexHarnessValidationError(`cacheWarm does not support "${unsupported}".`);
+  const clock: IFlexCacheWarmClock = options.clock ?? systemCacheWarmClock;
+  if (
+    !clock
+    || typeof clock !== 'object'
+    || typeof clock.now !== 'function'
+    || typeof clock.setTimeout !== 'function'
+    || typeof clock.clearTimeout !== 'function'
+  ) {
+    throw new FlexHarnessValidationError('cacheWarm.clock must provide now, setTimeout and clearTimeout.');
+  }
+  return Object.freeze({
+    maxDurationMs: resolveBoundedPositiveInteger(
+      options.maxDurationMs,
+      'cacheWarm.maxDurationMs',
+      defaultCacheWarmMaxDurationMs,
+      maximumCacheWarmMaxDurationMs,
+    ),
+    maxOutputTokens: resolveBoundedPositiveInteger(
+      options.maxOutputTokens,
+      'cacheWarm.maxOutputTokens',
+      defaultCacheWarmMaxOutputTokens,
+      maximumCacheWarmMaxOutputTokens,
+    ),
+    clock,
+  });
+}
+
 export function resolveBoundedPositiveInteger(
   value: number | undefined,
   name: string,

package/ts/utils.json.ts

@@ -566,7 +566,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   const activity = requireRecord(session.activity, `${path}.activity`);
   requireOnlyKeys(
     activity,
-    ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit', 'rejectedPermissionId'],
+    ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit', 'rejectedPermissionId', 'cacheWarm'],
     `${path}.activity`,
   );
   if (!activityStatuses.includes(activity.status as (typeof activityStatuses)[number])) {
@@ -578,6 +578,9 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   requireOptionalString(activity.error, `${path}.activity.error`);
   requireOptionalModelLimit(activity.limit, `${path}.activity.limit`);
   requireOptionalString(activity.rejectedPermissionId, `${path}.activity.rejectedPermissionId`);
+  if (activity.cacheWarm !== undefined && activity.cacheWarm !== true) {
+    throw new FlexHarnessStoreFormatError(`${path}.activity.cacheWarm must be true when present.`);
+  }
   const relationship = [
     session.parentSessionId,
     session.parentRunId,
@@ -776,6 +779,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       'limit',
       'rejectedPermissionId',
       'steerId',
+      'cacheWarm',
     ],
     path,
   );
@@ -799,6 +803,9 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       throw new FlexHarnessStoreFormatError(`${path}.steerId is only valid on a user message.`);
     }
   }
+  if (message.cacheWarm !== undefined && message.cacheWarm !== true) {
+    throw new FlexHarnessStoreFormatError(`${path}.cacheWarm must be true when present.`);
+  }
   if (message.model !== undefined) validateModel(message.model, `${path}.model`);
   if (message.usage !== undefined) validateUsage(message.usage, `${path}.usage`);
   if (!Array.isArray(message.parts)) {

package/ts/utils.sessionpreview.ts

@@ -1,13 +1,13 @@
 import { FLEX_PROJECT_MANAGEMENT_LIMITS, type IFlexMessage } from './interfaces.js';
 
 /**
- * What a session is about before anyone titles it: the text of its first prompt that has any, as
- * one line (every run of whitespace becomes one space), cut to the title bound at a character
- * boundary. Undefined while no prompt carries text.
+ * What a session is about before anyone titles it: the text of its first prompt that has any,
+ * cache-warm prompts aside, as one line (every run of whitespace becomes one space), cut to the
+ * title bound at a character boundary. Undefined while no prompt carries text.
  */
 export function sessionPreview(messagesArg: readonly IFlexMessage[]): string | undefined {
   for (const message of messagesArg) {
-    if (message.role !== 'user') continue;
+    if (message.role !== 'user' || message.cacheWarm) continue;
     const text = message.parts
       .map((part) => (part.type === 'text' ? part.text : ''))
       .join(' ')

package/ts_chat_harness/classes.transcript.ts

@@ -180,7 +180,7 @@ export class FlexHarnessTranscript {
   public view(): IFlexHarnessTranscriptView {
     return structuredClone({
       messages: this.flexMessages.flatMap((message, index) =>
-        flexMessageToHarnessRows(message, index, this.timings)),
+        message.cacheWarm ? [] : flexMessageToHarnessRows(message, index, this.timings)),
       permissions: [...this.permissionRows.values()],
       questions: [],
       status: this.status,
@@ -217,6 +217,11 @@ export class FlexHarnessTranscript {
     }
     if (event.scopeId !== this.scopeId || event.sessionId !== this.sessionId) return change;
     const timestamp = Date.parse(event.timestamp);
+    // A cache-warm turn's messages are held but not shown, so their events change no row.
+    const warmMessage = 'message' in event
+      ? event.message.cacheWarm === true
+      : 'messageId' in event && this.flexMessages.some((message) =>
+        message.messageId === event.messageId && message.cacheWarm);
     switch (event.type) {
       case 'session.created':
       case 'session.updated':
@@ -227,7 +232,7 @@ export class FlexHarnessTranscript {
         change.messages = change.permissions = change.status = change.usage = true;
         break;
       case 'run.started':
-        this.setStatus(change, { type: 'busy' });
+        if (!event.cacheWarm) this.setStatus(change, { type: 'busy' });
         break;
       case 'message.created':
       case 'message.updated':
@@ -280,13 +285,15 @@ export class FlexHarnessTranscript {
           this.usage = sumUsage(this.usage, flexUsageToHarness(event.message.usage));
           change.usage = true;
         }
+        if (event.cacheWarm) break;
         this.setStatus(change, event.status === 'failed'
           ? { type: 'error', ...(event.error ? { message: event.error.message } : {}) }
           : { type: 'idle' });
         break;
       case 'prompt.started':
       case 'prompt.running':
-        this.runningQueueId = event.queueId;
+        // A steer cannot join a cache-warm turn.
+        if (!event.entry.cacheWarm) this.runningQueueId = event.queueId;
         break;
       case 'prompt.finished':
         if (this.runningQueueId === event.queueId) this.runningQueueId = undefined;
@@ -297,6 +304,10 @@ export class FlexHarnessTranscript {
       default:
         break;
     }
+    if (warmMessage) {
+      change.messages = false;
+      change.deltas = [];
+    }
     return change;
   }
 

package/ts_chat_harness/functions.mapping.ts

@@ -215,7 +215,9 @@ export function flexPermissionToHarness(
   };
 }
 
+/** A cache-warm turn is idle time to the user: its activity shows as idle. */
 export function flexSessionToHarnessStatus(session: IFlexSession): plugins.IHarnessStatus {
+  if (session.activity.cacheWarm) return { type: 'idle' };
   switch (session.activity.status) {
     case 'running':
     case 'scheduled':
@@ -247,7 +249,7 @@ export function flexSessionToHarnessMeta(session: IFlexSession): plugins.IHarnes
     title: session.title ?? session.sessionId,
     ...(epoch(session.createdAt) === undefined ? {} : { createdAt: epoch(session.createdAt) }),
     ...(epoch(session.updatedAt) === undefined ? {} : { updatedAt: epoch(session.updatedAt) }),
-    state: sessionCardStates[session.activity.status],
+    state: session.activity.cacheWarm ? 'normal' : sessionCardStates[session.activity.status],
   };
 }