@modelprofile.com/flexharness 14.0.0 → 16.0.0

package/ts/utils.json.ts

@@ -473,6 +473,12 @@ function requireNonNegativeInteger(value: unknown, path: string): void {
   }
 }
 
+function requirePositiveInteger(value: unknown, path: string): void {
+  if (!Number.isSafeInteger(value) || Number(value) < 1) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a positive integer.`);
+  }
+}
+
 function requireStringArray(value: unknown, path: string): string[] {
   if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
     throw new FlexHarnessStoreFormatError(`${path} must be an array of strings.`);
@@ -545,10 +551,18 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
       'agent',
       'depth',
       'origin',
+      'contextCompaction',
     ],
     path,
   );
   requireString(session.scopeId, `${path}.scopeId`);
+  if (session.contextCompaction !== undefined) {
+    try {
+      plugins.assertAgentContextCompactionSetting(session.contextCompaction, `${path}.contextCompaction`);
+    } catch (error) {
+      throw new FlexHarnessStoreFormatError(error instanceof Error ? error.message : String(error));
+    }
+  }
   if (session.origin !== undefined) validateSessionOrigin(session.origin, `${path}.origin`);
   const sessionId = requireString(session.sessionId, `${path}.sessionId`);
   const generation = validateOptionalSessionGeneration(session, path);
@@ -748,6 +762,7 @@ interface IValidatedMessageIdentity {
   runId: string;
   role: 'user' | 'assistant';
   status: 'streaming' | 'completed' | 'failed' | 'cancelled';
+  steerId?: string;
 }
 
 interface IValidatedSessionIdentity {
@@ -781,6 +796,8 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       'limit',
       'rejectedPermissionId',
       'steerId',
+      'promptId',
+      'keptInContext',
       'cacheWarm',
     ],
     path,
@@ -805,6 +822,20 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       throw new FlexHarnessStoreFormatError(`${path}.steerId is only valid on a user message.`);
     }
   }
+  if (message.promptId !== undefined) {
+    requireString(message.promptId, `${path}.promptId`);
+    if (message.role !== 'user' || message.steerId !== undefined) {
+      throw new FlexHarnessStoreFormatError(`${path}.promptId is only valid on the user message that heads a run.`);
+    }
+  }
+  if (message.keptInContext !== undefined) {
+    if (typeof message.keptInContext !== 'boolean') {
+      throw new FlexHarnessStoreFormatError(`${path}.keptInContext must be boolean when present.`);
+    }
+    if (message.role !== 'user') {
+      throw new FlexHarnessStoreFormatError(`${path}.keptInContext is only valid on a user message.`);
+    }
+  }
   if (message.cacheWarm !== undefined && message.cacheWarm !== true) {
     throw new FlexHarnessStoreFormatError(`${path}.cacheWarm must be true when present.`);
   }
@@ -902,6 +933,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
     runId,
     role: message.role,
     status: message.status as IValidatedMessageIdentity['status'],
+    ...(message.steerId === undefined ? {} : { steerId: message.steerId as string }),
   };
 }
 
@@ -1196,7 +1228,7 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
 
 interface IValidatedProjectionBody {
   messages: IValidatedMessageIdentity[];
-  stagedUsers: IValidatedMessageIdentity[];
+  stagedMessages: IValidatedMessageIdentity[];
 }
 
 function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedProjectionBody {
@@ -1210,7 +1242,7 @@ function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedPr
   }
   const runIds = new Set<string>();
   const stagedMessageIds = new Set<string>();
-  const stagedUsers: IValidatedMessageIdentity[] = [];
+  const stagedMessages: IValidatedMessageIdentity[] = [];
   for (let index = 0; index < snapshot.stagedTerminals.length; index++) {
     const path = `$snapshot.stagedTerminals[${index}]`;
     const terminal = requireRecord(snapshot.stagedTerminals[index], path);
@@ -1236,26 +1268,33 @@ function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedPr
     if (!['completed', 'failed', 'cancelled'].includes(String(terminal.status))) {
       throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
     }
-    const user = validateMessage(terminal.userMessage, `${path}.userMessage`);
+    const user = terminal.userMessage === undefined
+      ? undefined
+      : validateMessage(terminal.userMessage, `${path}.userMessage`);
     const assistant = validateMessage(terminal.assistantMessage, `${path}.assistantMessage`);
-    if (user.role !== 'user' || assistant.role !== 'assistant') {
+    if ((user && user.role !== 'user') || assistant.role !== 'assistant') {
       throw new FlexHarnessStoreFormatError(`${path} has invalid terminal message roles.`);
     }
-    if (user.runId !== runId || assistant.runId !== runId || user.sessionId !== assistant.sessionId) {
+    if ((user && (user.runId !== runId || user.sessionId !== assistant.sessionId)) || assistant.runId !== runId) {
       throw new FlexHarnessStoreFormatError(`${path} has uncorrelated terminal messages.`);
     }
     if (assistant.status !== terminal.status) {
       throw new FlexHarnessStoreFormatError(`${path}.status does not match its assistant message.`);
     }
-    if (user.status !== terminal.status) {
+    if (!user && visibleMessages.some((message) =>
+      message.runId === runId && message.role === 'user' && message.steerId === undefined)) {
+      throw new FlexHarnessStoreFormatError(`${path} omits its projected prompt message.`);
+    }
+    if (user && user.status !== terminal.status) {
       throw new FlexHarnessStoreFormatError(`${path}.status does not match its user message.`);
     }
-    stagedUsers.push(user);
-    projectionSessionId ??= user.sessionId;
-    if (user.sessionId !== projectionSessionId) {
+    if (user) stagedMessages.push(user);
+    stagedMessages.push(assistant);
+    projectionSessionId ??= assistant.sessionId;
+    if (assistant.sessionId !== projectionSessionId) {
       throw new FlexHarnessStoreFormatError(`${path} belongs to another session.`);
     }
-    for (const messageId of [user.messageId, assistant.messageId]) {
+    for (const messageId of [...(user ? [user.messageId] : []), assistant.messageId]) {
       if (stagedMessageIds.has(messageId)) {
         throw new FlexHarnessStoreFormatError(
           `Snapshot staged terminals contain duplicate message "${messageId}".`,
@@ -1268,7 +1307,7 @@ function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedPr
     requireOptionalString(terminal.finishReason, `${path}.finishReason`);
     if (terminal.steps !== undefined) requireNonNegativeInteger(terminal.steps, `${path}.steps`);
   }
-  return { messages: visibleMessages, stagedUsers };
+  return { messages: visibleMessages, stagedMessages };
 }
 
 export function assertFlexProjectionSnapshotV1(
@@ -1328,7 +1367,7 @@ export function assertFlexProjectionSnapshotV2(
       'workspaceReference',
     ], path);
     const runId = requireString(segment.runId, `${path}.runId`);
-    const userMessageId = requireString(segment.userMessageId, `${path}.userMessageId`);
+    const userMessageId = requireOptionalString(segment.userMessageId, `${path}.userMessageId`);
     if (segmentRunIds.has(runId)) {
       throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate reversion run "${runId}".`);
     }
@@ -1384,12 +1423,19 @@ export function assertFlexProjectionSnapshotV2(
         throw new FlexHarnessStoreFormatError(`${path}.workspaceReference exceeds its byte limit.`);
       }
     }
-    const correlatedUsers = new Set([...projectionBody.messages, ...projectionBody.stagedUsers]
+    const projectedMessages = [...projectionBody.messages, ...projectionBody.stagedMessages];
+    if (userMessageId === undefined && projectedMessages.some((message) =>
+      message.runId === runId && message.role === 'user' && message.steerId === undefined)) {
+      throw new FlexHarnessStoreFormatError(`${path} omits its projected prompt identity.`);
+    }
+    const correlatedMessages = new Set(projectedMessages
       .filter((message) =>
-        message.role === 'user' && message.runId === runId && message.messageId === userMessageId)
+        message.runId === runId && (userMessageId === undefined
+          ? message.role === 'assistant'
+          : message.role === 'user' && message.messageId === userMessageId))
       .map((message) => `${message.runId}:${message.messageId}`));
-    if (correlatedUsers.size !== 1) {
-      throw new FlexHarnessStoreFormatError(`${path} does not match exactly one projected user message.`);
+    if (userMessageId === undefined ? correlatedMessages.size === 0 : correlatedMessages.size !== 1) {
+      throw new FlexHarnessStoreFormatError(`${path} does not match its projected turn messages.`);
     }
   }
   requireNonNegativeInteger(snapshot.revertCursor, '$snapshot.revertCursor');
@@ -1583,8 +1629,19 @@ function assertSessionMetrics(value: unknown): void {
   requireOnlyKeys(metrics, [
     'reportedLifetimeUsedTokens', 'reportedLifetimeUsedTokensExact', 'lifetimeUsageComplete',
     'pendingGenerationId', 'pendingCompactionId', 'lastObservedInputTokens', 'lastObservedInputTokensAt',
+    'contextWindow', 'contextCompactionTokens', 'contextCompactionOff',
     ...sessionMetricsBreakdownKeys,
   ], path);
+  for (const key of ['contextWindow', 'contextCompactionTokens']) {
+    if (Object.hasOwn(metrics, key)) requirePositiveInteger(metrics[key], `${path}.${key}`);
+  }
+  if (Object.hasOwn(metrics, 'contextCompactionOff')
+    && !['disabled', 'no-context-window', 'no-compactor'].includes(metrics.contextCompactionOff as string)) {
+    throw new FlexHarnessStoreFormatError(`${path}.contextCompactionOff is invalid.`);
+  }
+  if (Object.hasOwn(metrics, 'contextCompactionOff') && Object.hasOwn(metrics, 'contextCompactionTokens')) {
+    throw new FlexHarnessStoreFormatError(`${path} states both a compaction point and why there is none.`);
+  }
   requireNonNegativeInteger(metrics.reportedLifetimeUsedTokens, `${path}.reportedLifetimeUsedTokens`);
   for (const key of ['reportedLifetimeUsedTokensExact', 'lifetimeUsageComplete']) {
     if (typeof metrics[key] !== 'boolean') throw new FlexHarnessStoreFormatError(`${path}.${key} must be boolean.`);
@@ -1802,7 +1859,7 @@ export function assertFlexProjectionSnapshotV3(
       const segment = entry as Record<string, unknown>;
       return {
         runId: segment.runId,
-        userMessageId: segment.userMessageId,
+        ...(segment.userMessageId === undefined ? {} : { userMessageId: segment.userMessageId }),
         status: segment.status,
         contextAvailable: segment.contextAvailable,
         eventIds: segment.eventIds,
@@ -1860,7 +1917,7 @@ function assertProjectionSession(
   }
   for (const terminal of snapshot.stagedTerminals) {
     if (
-      terminal.userMessage.sessionId !== sessionId
+      (terminal.userMessage !== undefined && terminal.userMessage.sessionId !== sessionId)
       || terminal.assistantMessage.sessionId !== sessionId
     ) {
       throw new FlexHarnessStoreFormatError(

package/ts/utils.sessionmetrics.ts

@@ -1,9 +1,16 @@
 import type {
   IFlexSessionMetrics,
   IFlexSessionMetricsState,
+  TFlexContextCompactionOff,
   TFlexModelCallUsage,
 } from './interfaces.js';
 
+/** The compaction point a generation resolved for its model, recorded when it settles. */
+export interface ISessionMetricsContextCompaction {
+  contextWindow?: number;
+  point: { tokens: number } | { off: TFlexContextCompactionOff };
+}
+
 /** Fixed-size accumulator. One owner per generation / actual compactor invocation. */
 export interface ISessionMetricsOperation {
   id: string;
@@ -19,6 +26,8 @@ export interface ISessionMetricsOperation {
   breakdownExact: boolean;
   lastObservedInputTokens?: number;
   lastObservedInputTokensAt?: string;
+  /** Set on a generation once its model is resolved. */
+  contextCompaction?: ISessionMetricsContextCompaction;
 }
 
 export const createSessionMetricsState = (complete: boolean): IFlexSessionMetricsState => ({
@@ -109,6 +118,15 @@ export function settleSessionMetricsOperation(
     metrics.lastObservedInputTokens = operation.lastObservedInputTokens;
     metrics.lastObservedInputTokensAt = operation.lastObservedInputTokensAt;
   }
+  if (operation.contextCompaction !== undefined) {
+    const { contextWindow, point } = operation.contextCompaction;
+    delete metrics.contextWindow;
+    delete metrics.contextCompactionTokens;
+    delete metrics.contextCompactionOff;
+    if (contextWindow !== undefined) metrics.contextWindow = contextWindow;
+    if ('tokens' in point) metrics.contextCompactionTokens = point.tokens;
+    else metrics.contextCompactionOff = point.off;
+  }
   delete metrics[key];
 }
 
@@ -130,5 +148,10 @@ export function sessionMetricsView(metrics: IFlexSessionMetricsState): IFlexSess
       lastObservedInputTokensAt: metrics.lastObservedInputTokensAt,
       lastObservedInputTokensFreshness: 'historical' as const,
     }),
+    ...(metrics.contextWindow === undefined ? {} : { contextWindow: metrics.contextWindow }),
+    ...(metrics.contextCompactionTokens === undefined
+      ? {}
+      : { contextCompactionTokens: metrics.contextCompactionTokens }),
+    ...(metrics.contextCompactionOff === undefined ? {} : { contextCompactionOff: metrics.contextCompactionOff }),
   };
 }

package/ts/utils.transfer.ts

@@ -82,6 +82,15 @@ export function normalizeModelIdentity(identity: IFlexModelIdentity): IFlexModel
 }
 
 export function normalizeResolvedModel(resolvedModel: IFlexResolvedModel): IFlexResolvedModel {
+  for (const key of ['contextWindow', 'contextCompactionDefaultTokens'] as const) {
+    const tokens = resolvedModel[key];
+    if (tokens !== undefined && (!Number.isSafeInteger(tokens) || tokens < 1)) {
+      throw new FlexHarnessValidationError(`The resolved model's ${key} must be a positive integer.`);
+    }
+  }
+  if (resolvedModel.contextCompactionDefaultTokens !== undefined && resolvedModel.contextWindow === undefined) {
+    throw new FlexHarnessValidationError('The resolved model states contextCompactionDefaultTokens without contextWindow.');
+  }
   return {
     model: resolvedModel.model,
     identity: normalizeModelIdentity(resolvedModel.identity),
@@ -91,6 +100,10 @@ export function normalizeResolvedModel(resolvedModel: IFlexResolvedModel): IFlex
       : { providerOptions: resolvedModel.providerOptions }),
     ...(resolvedModel.cache === undefined ? {} : { cache: resolvedModel.cache }),
     ...(resolvedModel.maxSteps === undefined ? {} : { maxSteps: resolvedModel.maxSteps }),
+    ...(resolvedModel.contextWindow === undefined ? {} : { contextWindow: resolvedModel.contextWindow }),
+    ...(resolvedModel.contextCompactionDefaultTokens === undefined
+      ? {}
+      : { contextCompactionDefaultTokens: resolvedModel.contextCompactionDefaultTokens }),
   };
 }
 

package/ts/utils.validation.ts

@@ -16,6 +16,7 @@ import type {
   IFlexSlashCommandExecutionOptions,
   IFlexUpdateProjectTaskInput,
   IFlexUpdateSessionOptions,
+  TFlexContextCompactionSetting,
   TFlexProjectTaskPriority,
   TFlexProjectTaskStatus,
 } from './interfaces.js';
@@ -228,13 +229,34 @@ export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
   });
 }
 
-export function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions): void {
+/**
+ * Throws a `FlexHarnessValidationError` unless `value` is a valid compaction setting, and unless a
+ * setting other than `false` has a compactor to act with.
+ */
+export function validateContextCompactionSetting(
+  value: unknown,
+  hasCompactor: boolean,
+  path = 'contextCompaction',
+): asserts value is TFlexContextCompactionSetting {
+  try {
+    plugins.assertAgentContextCompactionSetting(value, path);
+  } catch (error) {
+    throw new FlexHarnessValidationError(error instanceof Error ? error.message : String(error));
+  }
+  if (value !== false && !hasCompactor) {
+    throw new FlexHarnessValidationError(`${path} requires a contextCompactor.`);
+  }
+}
+
+export function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions, hasCompactor: boolean): void {
   if (!options || typeof options !== 'object' || Array.isArray(options)) {
     throw new FlexHarnessValidationError('updateSession options must be a plain object.');
   }
   const keys = Object.keys(options);
-  if (keys.length === 0) throw new FlexHarnessValidationError('updateSession requires title or archived.');
-  const unsupportedKey = keys.find((key) => key !== 'title' && key !== 'archived');
+  if (keys.length === 0) {
+    throw new FlexHarnessValidationError('updateSession requires title, archived or contextCompaction.');
+  }
+  const unsupportedKey = keys.find((key) => key !== 'title' && key !== 'archived' && key !== 'contextCompaction');
   if (unsupportedKey) throw new FlexHarnessValidationError(`updateSession does not support "${unsupportedKey}".`);
   if (Object.prototype.hasOwnProperty.call(options, 'title') && options.title !== null) {
     validateUtf8String(
@@ -247,6 +269,9 @@ export function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions)
   if (Object.prototype.hasOwnProperty.call(options, 'archived') && typeof options.archived !== 'boolean') {
     throw new FlexHarnessValidationError('archived must be a boolean.');
   }
+  if (Object.prototype.hasOwnProperty.call(options, 'contextCompaction') && options.contextCompaction !== null) {
+    validateContextCompactionSetting(options.contextCompaction, hasCompactor);
+  }
 }
 
 export function validateProjectTaskStatus(value: unknown): asserts value is TFlexProjectTaskStatus {
@@ -317,10 +342,11 @@ export function validatePromptOptions(options: IFlexPromptOptions, scheduled: bo
     throw new FlexHarnessValidationError('Prompt options must be a plain object.');
   }
   const supported = scheduled
-    ? ['modelHint', 'system', 'maxSteps', 'debounceMs']
-    : ['modelHint', 'system', 'maxSteps'];
+    ? ['promptId', 'modelHint', 'system', 'maxSteps', 'debounceMs']
+    : ['promptId', 'modelHint', 'system', 'maxSteps'];
   const unsupported = Object.keys(options).find((key) => !supported.includes(key));
   if (unsupported) throw new FlexHarnessValidationError(`Prompt options do not support "${unsupported}".`);
+  if (options.promptId !== undefined) validateIdentifier(options.promptId, 'promptId');
   if (options.modelHint !== undefined) validateIdentifier(options.modelHint, 'modelHint');
   if (options.system !== undefined) validateIdentifier(options.system, 'system');
   if (options.maxSteps !== undefined && (!Number.isSafeInteger(options.maxSteps) || options.maxSteps < 1)) {