@modelprofile.com/flexharness 13.1.0 → 13.2.0

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],
   };
 }
 

package/ts_chat_harness/readme.md

@@ -78,6 +78,7 @@ The host forwards every event of the harness instance, of every session, in orde
 - Permission rows stay in the transcript once answered, showing the decision. A request its run leaves unanswered, because the run was stopped or failed, is removed when the run finishes.
 - FlexHarness emits no event for project state. After a run, or after a project tool's row completes, read `getProjectState()` and pass it to `applyProjectState()` for the task list and the scratchpad.
 - `questions` is always empty: FlexHarness has no question requests.
+- A cache-warm turn (see the FlexHarness readme, Keeping the Prompt Cache Warm) has no rows and leaves the status idle, the session card normal and `activeQueueId` unset, so a steer never joins it. Its usage still counts in `usage`: it is spent.
 - Messages the session has not taken in yet (a queued prompt, a steer) carry no text in FlexHarness events. The host that sent them shows them as pending rows.
 - An attachment row needs a name, a media type and a size. The public projection keeps no payload and states these only when the prompt did, so an attachment without all three, such as a remote URL of unknown size, has no row.