@modelprofile.com/flexharness 13.3.0 → 15.0.0

package/ts/classes.flexharness.prompts.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import {
   FlexHarnessAbortError,
+  FlexHarnessDuplicatePromptError,
   FlexHarnessNotFoundError,
   FlexHarnessQueueFullError,
   FlexHarnessSessionBusyError,
@@ -372,6 +373,7 @@ export class FlexHarnessPromptQueue<TScope> {
     queued?: IQueuedPrompt;
   }> {
     this.core.assertOpen();
+    if (options.promptId !== undefined) requireTransferIdentifier(options.promptId, 'promptId');
     const normalizedPrompt = normalizeFlexPrompt(prompt, this.core.attachmentReferenceProtocols);
     const normalizedOptions = cloneSerializable(options);
     const byteSize = this.promptAdmissionByteSize(prompt, options, scheduleKey, debounceMs);
@@ -459,6 +461,12 @@ export class FlexHarnessPromptQueue<TScope> {
       ) {
         throw new FlexHarnessSessionBusyError(sessionId, `already has scheduled key "${scheduleKey}"`);
       }
+      if (
+        options.promptId !== undefined
+        && [...stored.outstandingPromptsById.values()].some((entry) => entry.promptId === options.promptId)
+      ) {
+        throw new FlexHarnessDuplicatePromptError(options.promptId);
+      }
       let resolveCompletion!: (result: IFlexPromptResult) => void;
       let rejectCompletion!: (error: unknown) => void;
       const completion = new Promise<IFlexPromptResult>((resolve, reject) => {
@@ -485,6 +493,7 @@ export class FlexHarnessPromptQueue<TScope> {
         queuedAt: new Date().toISOString(),
         ...(scheduleKey === undefined ? {} : { scheduleKey, debounceMs }),
         ...(cacheWarm ? { cacheWarm: true as const } : {}),
+        ...(options.promptId === undefined ? {} : { promptId: options.promptId }),
         prompt: normalizedPrompt,
         options: normalizedOptions,
         ...(delegationSeed === undefined ? {} : { delegationSeed }),
@@ -641,7 +650,7 @@ export class FlexHarnessPromptQueue<TScope> {
           ),
         );
         this.assertPromptPromotion(queued, run);
-        const reservation = this.core.runs.createReservation(run, prompt);
+        const reservation = this.core.runs.createReservation(run, prompt, queued.promptId);
         closeReservationPublication = this.core.openPublication(run.state, run.sessionId);
         run.metricsOperation = createSessionMetricsOperation(run.runId, 'generation');
         await this.core.mutateProjection(run.state, run.stored, () => {
@@ -818,6 +827,7 @@ export class FlexHarnessPromptQueue<TScope> {
       status: queued.status,
       queuedAt: queued.queuedAt,
       ...(queued.runId ? { runId: queued.runId } : {}),
+      ...(queued.promptId === undefined ? {} : { promptId: queued.promptId }),
       ...(queued.scheduleKey ? { scheduleKey: queued.scheduleKey } : {}),
       ...(queued.cacheWarm ? { cacheWarm: true } : {}),
       ...(queued.startedAt ? { startedAt: queued.startedAt } : {}),

package/ts/classes.flexharness.reversions.ts

@@ -1224,8 +1224,16 @@ export class FlexHarnessReversions<TScope> {
       const nextCandidate = candidates[1];
       let end = 0;
       if (!firstCandidate) {
-        if (dropNonUndoablePrefix) end = stored.reversionSegments.length;
-        else if (overLimit) {
+        // Unsuccessful turns with output still contribute to model context. Keep their
+        // segments so the next completed turn can group (and undo) that leading history.
+        const firstVisibleSegment = dropNonUndoablePrefix
+          ? stored.reversionSegments.findIndex((segment) => plugins.isGenerationInModelContext(
+              stored.agentSession.getEvents(), segment.runId,
+            ))
+          : -1;
+        if (dropNonUndoablePrefix && firstVisibleSegment !== 0) {
+          end = firstVisibleSegment < 0 ? stored.reversionSegments.length : firstVisibleSegment;
+        } else if (overLimit) {
           end = Math.max(
             1,
             stored.reversionSegments.length + (reserveSegment ? 1 : 0)

package/ts/classes.flexharness.runs.ts

@@ -186,7 +186,7 @@ export class FlexHarnessRuns<TScope> {
       if (!run.modelResolution) throw new FlexHarnessValidationError('Generation completed without a resolved model.');
       const closeReversion = await this.core.reversions.prepareRunReversionClose(run, 'completed');
       await this.core.admission.closeRunDelegatedRunAdmission(run);
-      const terminal = this.buildTerminal(run, 'completed', result);
+      let terminal = this.buildTerminal(run, 'completed', result);
       try {
         // The reversion segment closes in the save that stages the terminal.
         await this.core.mutateProjection(run.state, run.stored, () => {
@@ -209,6 +209,7 @@ export class FlexHarnessRuns<TScope> {
         throw projected;
       }
       run.steering.keptInContext = true;
+      terminal = this.withKeptInContext(terminal, true);
       this.core.reversions.refreshAutomaticArchiveHorizon(run.stored);
       run.phase = 'promoting';
       const closePublication = this.core.openPublication(run.state, run.sessionId);
@@ -351,7 +352,10 @@ export class FlexHarnessRuns<TScope> {
     const terminalError = publicStatus === 'cancelled'
       ? run.ownerCancellation ?? this.core.trustInternalError(new FlexHarnessAbortError())
       : safeError;
-    const terminal = this.buildTerminal(run, publicStatus, undefined, terminalError);
+    const terminal = this.withKeptInContext(
+      this.buildTerminal(run, publicStatus, undefined, terminalError),
+      run.steering.keptInContext === true,
+    );
     if (!this.core.isTombstoned(run)) {
       const closePublication = this.core.openPublication(run.state, run.sessionId);
       try {
@@ -564,6 +568,21 @@ export class FlexHarnessRuns<TScope> {
       } catch (error) {
         throw this.core.projectExternalError(run, error, 'toolProvider');
       }
+      const contextCompaction = run.stored.session.contextCompaction ?? this.core.agentSessionPolicy.contextCompaction;
+      if (run.metricsOperation) {
+        run.metricsOperation.contextCompaction = {
+          ...(model!.contextWindow === undefined ? {} : { contextWindow: model!.contextWindow }),
+          point: this.core.agentSessionPolicy.contextCompactor
+            ? plugins.resolveAgentContextCompactionPoint({
+                ...(model!.contextWindow === undefined ? {} : { contextWindow: model!.contextWindow }),
+                ...(model!.contextCompactionDefaultTokens === undefined
+                  ? {}
+                  : { contextCompactionDefaultTokens: model!.contextCompactionDefaultTokens }),
+                ...(contextCompaction === undefined ? {} : { setting: contextCompaction }),
+              })
+            : { off: 'no-compactor' },
+        };
+      }
       let closed = false;
       let closePromise: Promise<void> | undefined;
       const close = toolHandle?.close
@@ -596,6 +615,11 @@ export class FlexHarnessRuns<TScope> {
         ...(model!.cache === undefined ? {} : { cache: model!.cache }),
         ...(options.maxSteps ?? model!.maxSteps ? { maxSteps: options.maxSteps ?? model!.maxSteps } : {}),
         ...(run.cacheWarm ? { maxOutputTokens: this.core.cacheWarmOptions.maxOutputTokens } : {}),
+        ...(model!.contextWindow === undefined ? {} : { contextWindow: model!.contextWindow }),
+        ...(model!.contextCompactionDefaultTokens === undefined
+          ? {}
+          : { contextCompactionDefaultTokens: model!.contextCompactionDefaultTokens }),
+        ...(contextCompaction === undefined ? {} : { contextCompaction }),
         ...(close ? { close } : {}),
       };
     } catch (error) {
@@ -706,6 +730,7 @@ export class FlexHarnessRuns<TScope> {
   public createReservation(
     run: IActiveRun,
     prompt: INormalizedFlexPrompt,
+    promptId?: string,
   ): { userMessage: IFlexMessage; assistantMessage: IFlexMessage } {
     const timestamp = new Date().toISOString();
     const userMessage: IFlexMessage = {
@@ -716,6 +741,7 @@ export class FlexHarnessRuns<TScope> {
       status: 'streaming',
       createdAt: timestamp,
       parts: this.userMessageParts(prompt),
+      ...(promptId === undefined ? {} : { promptId }),
       ...(run.cacheWarm ? { cacheWarm: true as const } : {}),
     };
     const assistantMessage: IFlexMessage = {
@@ -1029,6 +1055,14 @@ export class FlexHarnessRuns<TScope> {
     }, true);
   }
 
+  /**
+   * The terminal with its prompt's `keptInContext`: whether the run's result kept the prompt and
+   * the steers it took in in the model context. `replaceVisibleRun()` writes it onto the steers.
+   */
+  public withKeptInContext(terminal: IFlexTerminalProjection, keptInContext: boolean): IFlexTerminalProjection {
+    return { ...terminal, userMessage: { ...terminal.userMessage, keptInContext } };
+  }
+
   private replaceStagedTerminal(stored: IStoredSessionState, terminal: IFlexTerminalProjection): void {
     stored.stagedTerminals = stored.stagedTerminals.filter((entry) => entry.runId !== terminal.runId);
     stored.stagedTerminals.push(cloneSerializable(terminal));
@@ -1046,11 +1080,18 @@ export class FlexHarnessRuns<TScope> {
       [terminal.assistantMessage.messageId, terminal.assistantMessage],
     ]);
     const placed = new Set<string>();
+    const keptInContext = terminal.userMessage.keptInContext;
     stored.messages = stored.messages.map((message) => {
       const replacement = message.runId === terminal.runId
         ? replacements.get(message.messageId)
         : undefined;
-      if (!replacement) return message;
+      if (!replacement) {
+        // The steers the run took in share its prompt's outcome.
+        return keptInContext !== undefined && message.runId === terminal.runId && message.role === 'user'
+          && message.keptInContext !== keptInContext
+          ? { ...cloneSerializable(message), keptInContext }
+          : message;
+      }
       placed.add(replacement.messageId);
       return cloneSerializable(replacement);
     });
@@ -1089,7 +1130,10 @@ export class FlexHarnessRuns<TScope> {
         this.core.emitPartEvent(run, 'part.completed', part);
       }
     }
-    for (const message of [terminal.userMessage, terminal.assistantMessage]) {
+    const steerMessages = terminal.userMessage.keptInContext === undefined
+      ? []
+      : run.stored.messages.filter((message) => message.runId === run.runId && message.steerId !== undefined);
+    for (const message of [terminal.userMessage, ...steerMessages, terminal.assistantMessage]) {
       this.core.emitEvent(run.scopeId, run.stored.session, {
         type: 'message.updated',
         runId: run.runId,

package/ts/classes.flexharness.sessions.ts

@@ -11,6 +11,7 @@ import {
   type IFlexMessage,
   type IFlexMessagePage,
   type IFlexMessagePageOptions,
+  type IFlexMessageReadOptions,
   type IFlexSession,
   type IFlexSessionView,
   type IFlexSessionMetrics,
@@ -29,6 +30,7 @@ import {
   requireTransferIdentifier,
 } from './utils.transfer.js';
 import {
+  validateContextCompactionSetting,
   validateIdentifier,
   validateSessionGenerationId,
   validateSessionConfigurationRef,
@@ -51,6 +53,19 @@ import type { FlexHarnessCore } from './classes.flexharness.core.js';
 const maxSessionViewPasses = 64;
 
 /** Sessions and their messages: listing, creation, updates, views and message pages. */
+/** Validates transcript read options and states whether undone messages are included. */
+function readIncludeUndone(options: IFlexMessageReadOptions, name: string): boolean {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new FlexHarnessValidationError(`${name} must be a plain object.`);
+  }
+  const unsupported = Object.keys(options).find((key) => key !== 'includeUndone');
+  if (unsupported) throw new FlexHarnessValidationError(`${name} do not support "${unsupported}".`);
+  if (options.includeUndone !== undefined && typeof options.includeUndone !== 'boolean') {
+    throw new FlexHarnessValidationError('includeUndone must be a boolean.');
+  }
+  return options.includeUndone === true;
+}
+
 export class FlexHarnessSessions<TScope> {
   constructor(private readonly core: FlexHarnessCore<TScope>) {}
 
@@ -73,7 +88,7 @@ export class FlexHarnessSessions<TScope> {
       throw new FlexHarnessValidationError('createSession options must be a plain object.');
     }
     const unsupported = Object.keys(options).find(
-      (key) => !['sessionId', 'sessionGenerationId', 'configurationRef', 'title'].includes(key),
+      (key) => !['sessionId', 'sessionGenerationId', 'configurationRef', 'title', 'contextCompaction'].includes(key),
     );
     if (unsupported) throw new FlexHarnessValidationError(`createSession does not support "${unsupported}".`);
     const requestedSessionGenerationId = options.sessionGenerationId;
@@ -81,6 +96,12 @@ export class FlexHarnessSessions<TScope> {
       validateSessionGenerationId(requestedSessionGenerationId);
     }
     if (options.configurationRef !== undefined) validateSessionConfigurationRef(options.configurationRef);
+    if (options.contextCompaction !== undefined) {
+      validateContextCompactionSetting(
+        options.contextCompaction,
+        this.core.agentSessionPolicy.contextCompactor !== undefined,
+      );
+    }
     const resolved = await this.core.resolveState(scopeId);
     const sessionId = options.sessionId ?? plugins.crypto.randomUUID();
     validateIdentifier(sessionId, 'sessionId');
@@ -131,6 +152,9 @@ export class FlexHarnessSessions<TScope> {
           sessionGenerationSequence: resolved.state.revision + 1,
           ...(options.configurationRef === undefined ? {} : { configurationRef: options.configurationRef }),
           ...(options.title ? { title: options.title } : {}),
+          ...(options.contextCompaction === undefined
+            ? {}
+            : { contextCompaction: cloneSerializable(options.contextCompaction) }),
           createdAt: timestamp,
           updatedAt: timestamp,
           status: 'idle',
@@ -257,7 +281,7 @@ export class FlexHarnessSessions<TScope> {
     sessionId: string,
     options: IFlexUpdateSessionOptions,
   ): Promise<IFlexSession> {
-    validateUpdateSessionOptions(options);
+    validateUpdateSessionOptions(options, this.core.agentSessionPolicy.contextCompactor !== undefined);
     const { state } = await this.core.resolveState(scopeId);
     let result!: IFlexSession;
     await this.core.mutateScope(state, () => {
@@ -269,6 +293,10 @@ export class FlexHarnessSessions<TScope> {
         if (options.title === null) delete stored.session.title;
         else stored.session.title = options.title!;
       }
+      if (Object.prototype.hasOwnProperty.call(options, 'contextCompaction')) {
+        if (options.contextCompaction === null) delete stored.session.contextCompaction;
+        else stored.session.contextCompaction = cloneSerializable(options.contextCompaction!);
+      }
       if (options.archived === true) stored.session.archivedAt ??= timestamp;
       else if (options.archived === false) delete stored.session.archivedAt;
       stored.session.updatedAt = timestamp;
@@ -278,7 +306,12 @@ export class FlexHarnessSessions<TScope> {
     return result;
   }
 
-  public async getSessionView(scopeId: string, sessionId: string): Promise<IFlexSessionView> {
+  public async getSessionView(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexMessageReadOptions = {},
+  ): Promise<IFlexSessionView> {
+    const includeUndone = readIncludeUndone(options, 'Session view options');
     const { state } = await this.core.resolveState(scopeId);
     let stored = this.core.requireSession(state, sessionId);
     for (let pass = 0; ; pass++) {
@@ -301,7 +334,7 @@ export class FlexHarnessSessions<TScope> {
       ) break;
     }
     const run = state.activeRuns.get(sessionId);
-    const messages = this.core.visibleMessages(stored).map((message) => (
+    const messages = this.core.transcriptMessages(stored, includeUndone).map((message) => (
       run && run.stored === stored && message.messageId === run.assistantMessageId
         && message.status === 'streaming'
         ? { ...message, parts: run.callbackParts }
@@ -318,12 +351,17 @@ export class FlexHarnessSessions<TScope> {
     });
   }
 
-  public async getMessages(scopeId: string, sessionId: string): Promise<IFlexMessage[]> {
+  public async getMessages(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexMessageReadOptions = {},
+  ): Promise<IFlexMessage[]> {
+    const includeUndone = readIncludeUndone(options, 'Message read options');
     const { state } = await this.core.resolveState(scopeId);
     const stored = this.core.requireSession(state, sessionId);
     await stored.projectionQueue;
     this.core.assertStateAcceptingWork(state);
-    return publicSnapshot(this.core.visibleMessages(stored));
+    return publicSnapshot(this.core.transcriptMessages(stored, includeUndone));
   }
 
   public async listMessagePage(
@@ -334,8 +372,13 @@ export class FlexHarnessSessions<TScope> {
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
       throw new FlexHarnessValidationError('Message page options must be a plain object.');
     }
-    const unsupported = Object.keys(options).find((key) => key !== 'limit' && key !== 'before');
+    const unsupported = Object.keys(options)
+      .find((key) => key !== 'limit' && key !== 'before' && key !== 'includeUndone');
     if (unsupported) throw new FlexHarnessValidationError(`Message page options do not support "${unsupported}".`);
+    if (options.includeUndone !== undefined && typeof options.includeUndone !== 'boolean') {
+      throw new FlexHarnessValidationError('includeUndone must be a boolean.');
+    }
+    const includeUndone = options.includeUndone === true;
     const limit = options.limit ?? maxMessagePageSize;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxMessagePageSize) {
       throw new FlexHarnessValidationError(`Message page limit must be an integer from 1 through ${maxMessagePageSize}.`);
@@ -353,7 +396,7 @@ export class FlexHarnessSessions<TScope> {
     await stored.projectionQueue;
     this.core.assertStateAcceptingWork(state);
     const namespace = this.core.messageCursorNamespace(state.storageKey);
-    const visibleMessages = this.core.visibleMessages(stored);
+    const visibleMessages = this.core.transcriptMessages(stored, includeUndone);
     let end = visibleMessages.length;
     if (options.before !== undefined) {
       const cursor = this.core.parseMessageCursor(options.before);
@@ -394,14 +437,16 @@ export class FlexHarnessSessions<TScope> {
     scopeId: string,
     sessionId: string,
     messageId: string,
+    options: IFlexMessageReadOptions = {},
   ): Promise<IFlexMessage> {
+    const includeUndone = readIncludeUndone(options, 'Message read options');
     validateIdentifier(messageId, 'messageId');
     requireTransferIdentifier(messageId, 'messageId');
     const { state } = await this.core.resolveState(scopeId);
     const stored = this.core.requireSession(state, sessionId);
     await stored.projectionQueue;
     this.core.assertStateAcceptingWork(state);
-    return publicSnapshot(createBoundedTransferMessage(this.core.requireMessage(stored, messageId)));
+    return publicSnapshot(createBoundedTransferMessage(this.core.requireMessage(stored, messageId, includeUndone)));
   }
 
   public async pushRuntimeEvent(

package/ts/classes.flexharness.ts

@@ -15,6 +15,7 @@ import type {
   IFlexMessage,
   IFlexMessagePage,
   IFlexMessagePageOptions,
+  IFlexMessageReadOptions,
   IFlexPermissionRequest,
   IFlexProjectGoalResult,
   IFlexSteerAdmission,
@@ -246,12 +247,20 @@ export class FlexHarness<TScope = unknown> {
    * with the instance's event sequence they include. It waits until no queued projection or scope
    * write and no change that emits events for the session is in progress.
    */
-  public getSessionView(scopeId: string, sessionId: string): Promise<IFlexSessionView> {
-    return this.core.sessions.getSessionView(scopeId, sessionId);
+  public getSessionView(
+    scopeId: string,
+    sessionId: string,
+    options?: IFlexMessageReadOptions,
+  ): Promise<IFlexSessionView> {
+    return this.core.sessions.getSessionView(scopeId, sessionId, options);
   }
 
-  public getMessages(scopeId: string, sessionId: string): Promise<IFlexMessage[]> {
-    return this.core.sessions.getMessages(scopeId, sessionId);
+  public getMessages(
+    scopeId: string,
+    sessionId: string,
+    options?: IFlexMessageReadOptions,
+  ): Promise<IFlexMessage[]> {
+    return this.core.sessions.getMessages(scopeId, sessionId, options);
   }
 
   public listMessagePage(
@@ -266,8 +275,9 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
     messageId: string,
+    options?: IFlexMessageReadOptions,
   ): Promise<IFlexMessage> {
-    return this.core.sessions.getMessage(scopeId, sessionId, messageId);
+    return this.core.sessions.getMessage(scopeId, sessionId, messageId, options);
   }
 
   public listSlashCommands(

package/ts/errors.ts

@@ -68,6 +68,21 @@ export class FlexHarnessSteerRejectedError extends FlexHarnessError {
   }
 }
 
+/**
+ * A prompt names a `promptId` that an outstanding prompt of the same session, queued or running,
+ * already holds. A finished prompt's id is free again: its user message in the transcript shows
+ * that it ran.
+ */
+export class FlexHarnessDuplicatePromptError extends FlexHarnessError {
+  public readonly promptId: string;
+
+  constructor(promptId: string) {
+    super('FLEX_PROMPT_DUPLICATE', `Prompt "${promptId}" is already outstanding in this session.`);
+    this.name = 'FlexHarnessDuplicatePromptError';
+    this.promptId = promptId;
+  }
+}
+
 /** An operation would change the history or model context of an imported, read-only session. */
 export class FlexHarnessImportedSessionError extends FlexHarnessError {
   public readonly sessionId: string;

package/ts/index.ts

@@ -3,6 +3,12 @@ export * from './classes.stores.js';
 export { FlexToolCatalog } from './classes.toolcatalog.js';
 export * from './errors.js';
 export * from './interfaces.js';
+export {
+  AGENT_CONTEXT_COMPACTION_CEILING_PERCENT,
+  getAgentContextCompactionCeiling,
+  resolveAgentContextCompactionPoint,
+} from './plugins.js';
+export type { IAgentContextCompactionInput, TAgentContextCompactionPoint } from './plugins.js';
 export {
   createFlexToolPermissionRequester,
   type IFlexToolPermissionRequesterOptions,

package/ts/interfaces.flexharness.ts

@@ -412,6 +412,8 @@ export interface IQueuedPrompt {
   debounceMs?: number;
   /** A cache-warm prompt of the session's cache keeper; see `keepCacheWarm()`. */
   cacheWarm?: true;
+  /** The prompt's `promptId`; kept after its payload is released. */
+  promptId?: string;
   startedAt?: string;
   prompt?: INormalizedFlexPrompt;
   options?: IFlexPromptOptions;

package/ts/interfaces.ts

@@ -92,8 +92,36 @@ export interface IFlexSessionMetricsState {
   reportedLifetimeCacheWriteTokens?: number;
   /** The breakdown counts every call since the session began, without saturation. */
   lifetimeTokenBreakdownComplete?: boolean;
+  /** The served context window of the last settled run's model; see `IFlexSessionMetrics`. */
+  contextWindow?: number;
+  /** The last settled run's compaction point; exclusive with `contextCompactionOff`. */
+  contextCompactionTokens?: number;
+  /** Why the last settled run had no compaction point; exclusive with `contextCompactionTokens`. */
+  contextCompactionOff?: TFlexContextCompactionOff;
 }
 
+/**
+ * A session's choice of its proactive compaction point, in tokens of the model in use.
+ *
+ * - `{ tokens }`: a positive integer, clamped at run time to the ceiling of the run's model (90%
+ *   of its served context window). Without a known served window it applies unclamped.
+ * - `{ percent }`: an integer from 1 through 90 of the served window. Without a known served
+ *   window the run has no proactive compaction.
+ * - `false`: no proactive compaction.
+ *
+ * Omitted, the model's default applies: the catalog's automatic compaction point
+ * (`IFlexResolvedModel.contextCompactionDefaultTokens`) when stated, at most the ceiling,
+ * otherwise the ceiling itself.
+ */
+export type TFlexContextCompactionSetting = plugins.TAgentContextCompactionSetting;
+
+/**
+ * Why a run had no proactive compaction point: the setting is `false` (`disabled`), the run's
+ * model states no served context window and the setting needs one (`no-context-window`), or the
+ * harness has no `contextCompactor` (`no-compactor`).
+ */
+export type TFlexContextCompactionOff = plugins.TAgentContextCompactionOff | 'no-compactor';
+
 /** No member estimates current context size or includes child-session / tool-owned model calls. */
 export interface IFlexSessionMetrics {
   /** Sum of durably settled per-call reports; a lower bound when incomplete. */
@@ -120,6 +148,19 @@ export interface IFlexSessionMetrics {
    * the session's calls were counted by input and cache since it began.
    */
   lifetimeTokenBreakdownComplete: boolean;
+  /**
+   * The served context window, in tokens, of the model the last settled run resolved; absent when
+   * that model states none or before the first run.
+   */
+  contextWindow?: number;
+  /**
+   * The proactive compaction point the last settled run used, in tokens. Exactly one of it and
+   * `contextCompactionOff` is present once a run settled; neither before. A changed session
+   * setting shows from the next run; `resolveAgentContextCompactionPoint` states it before.
+   */
+  contextCompactionTokens?: number;
+  /** Why the last settled run had no proactive compaction point. */
+  contextCompactionOff?: TFlexContextCompactionOff;
 }
 
 export interface IFlexModelIdentity {
@@ -222,6 +263,21 @@ export interface IFlexMessage {
   rejectedPermissionId?: string;
   /** On a user message that steered its running run: the caller's steer identity. */
   steerId?: string;
+  /** On the user message that heads a run: the caller's prompt identity, when the prompt named one. */
+  promptId?: string;
+  /**
+   * On a user message, once its run reached its terminal state: whether the run's result kept this
+   * message in the model context of later turns, the value the run's `keptInContext` reports. It
+   * records that outcome and is never rewritten afterwards: an undo is reported by `undone`, and a
+   * later compaction summarizes the message, which was still delivered. Absent on a message whose
+   * run has not ended, and on messages written before FlexHarness 15.0.0.
+   */
+  keptInContext?: boolean;
+  /**
+   * Set only by a read with `includeUndone`: the message belongs to an undone turn that a redo can
+   * bring back. Never stored.
+   */
+  undone?: true;
   /**
    * 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.
@@ -268,6 +324,8 @@ export interface IFlexSession {
   depth?: number;
   /** Set only on a session the staged session import created; such a session is read-only. */
   origin?: IFlexSessionOrigin;
+  /** The session's compaction setting; absent for the harness default. */
+  contextCompaction?: TFlexContextCompactionSetting;
 }
 
 /** The position of an imported session when one source conversation was split into several sessions. */
@@ -394,16 +452,28 @@ export interface IFlexCreateSessionOptions {
   sessionGenerationId?: string;
   configurationRef?: string;
   title?: string;
+  /** The session's compaction setting; omitted for the harness default. */
+  contextCompaction?: TFlexContextCompactionSetting;
 }
 
 export interface IFlexUpdateSessionOptions {
   title?: string | null;
   archived?: boolean;
+  /** The session's compaction setting; `null` returns the session to the harness default. */
+  contextCompaction?: TFlexContextCompactionSetting | null;
 }
 
 export interface IFlexPromptOptions {
+  /**
+   * The caller's identity for this prompt, a non-empty string of at most 512 UTF-8 bytes. It is on
+   * the prompt's queue entry and on the user message that heads its run, so a caller can tell
+   * exactly whether the prompt was taken in. An outstanding prompt of the session holding the same
+   * id rejects the admission with `FlexHarnessDuplicatePromptError`.
+   */
+  promptId?: string;
   modelHint?: string;
   system?: string;
+  /** Optional positive safe integer step cap; no limit unless configured. */
   maxSteps?: number;
 }
 
@@ -527,6 +597,8 @@ export interface IFlexPromptQueueEntry {
   status: TFlexPromptQueueStatus;
   queuedAt: string;
   runId?: string;
+  /** The prompt's `promptId`, when it named one. */
+  promptId?: string;
   scheduleKey?: string;
   /** The entry is a cache-warm prompt; see {@link IFlexMessage.cacheWarm}. */
   cacheWarm?: true;
@@ -605,7 +677,16 @@ export interface IFlexScheduledPromptAdmission extends IFlexPromptAdmission {
   scheduleKey: string;
 }
 
-export interface IFlexMessagePageOptions {
+/** Options of the transcript reads. */
+export interface IFlexMessageReadOptions {
+  /**
+   * Also return the messages of undone turns, each marked `undone: true`, in their place after the
+   * visible ones. Messages a committed branch removed are gone and never returned.
+   */
+  includeUndone?: boolean;
+}
+
+export interface IFlexMessagePageOptions extends IFlexMessageReadOptions {
   limit?: number;
   before?: string;
 }
@@ -666,7 +747,21 @@ export interface IFlexResolvedModel {
   system?: string;
   providerOptions?: TFlexAgentProviderOptions;
   cache?: TFlexAgentCacheSetting;
+  /** Optional positive safe integer step cap; no limit unless configured. */
   maxSteps?: number;
+  /**
+   * The model's served context window in tokens, from the provider's catalog: the window the
+   * provider serves by default, never an extended maximum (for a Codex catalog `context_window`,
+   * not `max_context_window`; for Anthropic's Models API `max_input_tokens`). Omitted when the
+   * catalog states none: the run then has a compaction point only from a `{ tokens }` setting.
+   */
+  contextWindow?: number;
+  /**
+   * The catalog's own automatic compaction point in tokens, when it states one (a Codex catalog's
+   * `auto_compact_token_limit`). It lowers the default point, never the ceiling. Requires
+   * `contextWindow`.
+   */
+  contextCompactionDefaultTokens?: number;
 }
 
 export interface IFlexModelResolver<TScope> {
@@ -1889,7 +1984,11 @@ export type TFlexAgentContextCompactor<TScope = unknown> = (
 export interface IFlexAgentSessionPolicy<TScope = unknown> {
   contextBuilder?: plugins.TAgentContextBuilder;
   contextCompactor?: TFlexAgentContextCompactor<TScope>;
-  contextCompactionBytes?: plugins.IAgentSessionOptions['contextCompactionBytes'];
+  /**
+   * The harness default compaction setting, for sessions without their own. Omitted, the model's
+   * default applies. Requires `contextCompactor` unless `false`.
+   */
+  contextCompaction?: TFlexContextCompactionSetting;
   eventRetention?: TFlexAgentSessionOptions['eventRetention'];
   changeListenerTimeoutMs?: number;
   maxPendingSessionChanges?: number;
@@ -1903,6 +2002,7 @@ export interface IFlexSubagentDefinition {
   description: string;
   modelHint?: string;
   system?: string;
+  /** Optional positive safe integer step cap; no limit unless configured. */
   maxSteps?: number;
   /** Exact model-facing names permitted for this agent; omitted means unrestricted. */
   allowedTools?: readonly string[];
@@ -2120,9 +2220,8 @@ export interface IFlexPartDeltaEvent extends IFlexPartEventBase {
 }
 
 /**
- * A streamed part left its message: the model call that streamed it failed and is retried, and
- * the retry streams its own parts. `partIndex` is the part's position before it left; the parts
- * after it move up by one.
+ * A part left its message. `partIndex` is its position before it left; the parts after it
+ * move up by one. Failed-inference observations are retained, not removed for a retry.
  */
 export interface IFlexPartRemovedEvent extends IFlexPartEventBase {
   readonly type: 'part.removed';