@modelprofile.com/flexharness 14.0.0 → 16.0.0

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,14 +452,25 @@ 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. */
@@ -528,7 +597,11 @@ export interface IFlexPromptQueueEntry {
   status: TFlexPromptQueueStatus;
   queuedAt: string;
   runId?: string;
+  /** The prompt's `promptId`, when it named one. */
+  promptId?: string;
   scheduleKey?: string;
+  /** This entry answers existing context without adding a prompt message. */
+  continuation?: true;
   /** The entry is a cache-warm prompt; see {@link IFlexMessage.cacheWarm}. */
   cacheWarm?: true;
   startedAt?: string;
@@ -537,8 +610,9 @@ export interface IFlexPromptQueueEntry {
   /**
    * On a finished entry: whether its prompt, the steers its run took in and what its model
    * produced stay in the model context of later turns. True for a completed run and a run
-   * stopped after its model produced output; false for a failed run, a run stopped before any
-   * model output and a prompt that never ran. Send the prompt again to have it answered.
+   * stopped or failed after its model produced output; false for an unsuccessful run without
+   * model output and a prompt that never ran. For a continuation, this describes only the new
+   * run's history; it does not change the retention of the existing input.
    */
   keptInContext?: boolean;
   /**
@@ -549,10 +623,10 @@ export interface IFlexPromptQueueEntry {
   unappliedSteerIds?: string[];
 }
 
-export interface IFlexPromptResult {
+/** The result of answering existing context, without adding a prompt message. */
+export interface IFlexContinuePromptResult {
   runId: string;
   sessionId: string;
-  userMessage: IFlexMessage;
   /** The run's last assistant message; a steered run completed earlier ones as it took steers in. */
   assistantMessage: IFlexMessage;
   model: IFlexModelIdentity;
@@ -563,6 +637,10 @@ export interface IFlexPromptResult {
   unappliedSteerIds: string[];
 }
 
+export interface IFlexPromptResult extends IFlexContinuePromptResult {
+  userMessage: IFlexMessage;
+}
+
 /** A message for the running run of a session, taken in at the run's next step boundary. */
 export interface IFlexSteerInput {
   /** Caller-chosen identity, unique among the steers of the run. */
@@ -576,12 +654,13 @@ export interface IFlexSteerAdmission {
   runId: string;
 }
 
-export interface IFlexPromptQueueAdmission {
+export interface IFlexPromptQueueAdmission<TResult extends IFlexContinuePromptResult = IFlexPromptResult> {
   queueId: string;
-  completion: Promise<IFlexPromptResult>;
+  completion: Promise<TResult>;
 }
 
-export interface IFlexPromptAdmission extends IFlexPromptQueueAdmission {
+export interface IFlexPromptAdmission<TResult extends IFlexContinuePromptResult = IFlexPromptResult>
+  extends IFlexPromptQueueAdmission<TResult> {
   runId: string;
 }
 
@@ -602,11 +681,27 @@ export interface IFlexEnqueuePromptOptions extends IFlexPromptOptions {
   steers?: readonly IFlexSteerInput[];
 }
 
+/** Options for continuation through the same FIFO, optionally with scheduled execution. */
+export interface IFlexContinuePromptOptions extends Omit<IFlexEnqueuePromptOptions, 'promptId'> {
+  scheduleKey?: string;
+  /** Requires scheduleKey; defaults to 50 ms when scheduled. */
+  debounceMs?: number;
+}
+
 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;
 }
@@ -669,6 +764,19 @@ export interface IFlexResolvedModel {
   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> {
@@ -1167,7 +1275,8 @@ export interface IFlexScopeSnapshot {
 export interface IFlexTerminalProjection {
   runId: string;
   status: 'completed' | 'failed' | 'cancelled';
-  userMessage: IFlexMessage;
+  /** Absent for a continuation, which creates no prompt message. */
+  userMessage?: IFlexMessage;
   assistantMessage: IFlexMessage;
   model?: IFlexModelIdentity;
   /** The usage the provider reported for the run's model calls, whatever the status. */
@@ -1195,7 +1304,8 @@ export interface IFlexAffectedWorkspace {
 
 interface IFlexReversionSegmentV2 {
   runId: string;
-  userMessageId: string;
+  /** Absent for an assistant-only continuation segment. */
+  userMessageId?: string;
   status: TFlexReversionSegmentStatus;
   contextAvailable: boolean;
   eventIds: string[];
@@ -1891,7 +2001,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;

package/ts/plugins.ts

@@ -92,6 +92,7 @@ export const importCodeSandboxEngine = async (): Promise<ICodeSandboxEngine> =>
 
 // @push.rocks scope
 import {
+  AGENT_CONTEXT_COMPACTION_CEILING_PERCENT,
   AgentEventStoreConflictError,
   AgentPendingInputQueue,
   applyAgentEventChange,
@@ -100,13 +101,16 @@ import {
   AgentPendingInputRejectedError,
   AgentSession,
   AgentToolCallScheduler,
+  assertAgentContextCompactionSetting,
   buildModelMessages,
+  getAgentContextCompactionCeiling,
   ToolJobStoreConflictError,
   createAgentEvent,
   filterModelVisibleAgentEvents,
   getAgentGenerationTransactions,
   isGenerationInModelContext,
   modelMessagesToAgentEvents,
+  resolveAgentContextCompactionPoint,
   tool,
   validateAgentEventArchive,
   validateAgentEventSnapshot,
@@ -114,6 +118,7 @@ import {
 } from '@modelprofile.com/flexharness-agent';
 
 export {
+  AGENT_CONTEXT_COMPACTION_CEILING_PERCENT,
   AgentEventStoreConflictError,
   AgentPendingInputQueue,
   applyAgentEventChange,
@@ -122,13 +127,16 @@ export {
   AgentPendingInputRejectedError,
   AgentSession,
   AgentToolCallScheduler,
+  assertAgentContextCompactionSetting,
   buildModelMessages,
+  getAgentContextCompactionCeiling,
   ToolJobStoreConflictError,
   createAgentEvent,
   filterModelVisibleAgentEvents,
   getAgentGenerationTransactions,
   isGenerationInModelContext,
   modelMessagesToAgentEvents,
+  resolveAgentContextCompactionPoint,
   tool,
   validateAgentEventArchive,
   validateAgentEventSnapshot,
@@ -141,6 +149,7 @@ export type {
   TSmartAiCacheBudgetBasis,
   IAgentEventArchive,
   IAgentEventChange,
+  IAgentContextCompactionInput,
   IAgentContextCompactionOptions,
   IAgentEventSnapshot,
   IAgentEventStore,
@@ -150,6 +159,7 @@ export type {
   IAgentRetryEvent,
   IAgentRunResult,
   IAgentSession,
+  IAgentContinuationSession,
   IAgentSessionOptions,
   IAgentToolCallUpdateEvent,
   IAgentToolExecutionOptions,
@@ -165,6 +175,9 @@ export type {
   IToolJobStore,
   IToolPermissionRequest,
   TAgentContextBuilder,
+  TAgentContextCompactionOff,
+  TAgentContextCompactionPoint,
+  TAgentContextCompactionSetting,
   TAgentContextCompactor,
   TAgentEvent,
   TAgentGenerationOutcome,

package/ts/readme.md

@@ -111,6 +111,9 @@ A warm read joins outstanding projection writes and surfaces accounting failures
 | `lastObservedInputTokensFreshness` | Always `historical`. This is **not** current context size: output, steering, compaction and reversion can change context. |
 | `reportedLifetimeInputTokens` | Sum of the settled per-call reports' input tokens, prompt-cache reads included. |
 | `reportedLifetimeCacheReadTokens`, `reportedLifetimeCacheWriteTokens` | Sums of the settled per-call reports' input tokens read from and written to the prompt cache. |
+| `contextWindow` | The served context window, in tokens, of the model the last settled run resolved; absent when that model states none. |
+| `contextCompactionTokens` | The compaction point the last settled run used, in tokens. |
+| `contextCompactionOff` | Why the last settled run had no compaction point: `disabled`, `no-context-window` or `no-compactor`. Exactly one of it and `contextCompactionTokens` is present once a run settled. |
 | `lifetimeTokenBreakdownComplete` | The three sums cover every call `lifetimeUsedTokens` covers: lifetime usage is complete and the session's calls were counted by input and cache since it began. Otherwise they are lower bounds. |
 
 Accounting covers this session's generation calls and reported compaction calls,
@@ -495,7 +498,7 @@ Sending requires the exact active parent run, its currently delegated direct chi
 
 Before creating or resuming a child, FlexHarness requests permission on the parent run with `kind: 'subagent.start'`, the parent `toolCallId`, and separately bounded harness-owned agent/task metadata. Its metadata includes `childSessionId`, the exact ID reserved for this call: FlexHarness derives it deterministically when `taskId` is omitted and copies the supplied candidate when `taskId` is present. A resume also retains that candidate as `taskId`. This block is not truncated by `toolOutputLimits`. The reserved ID binds permission handling before child creation but does not prove that the child exists or is owned: applications must treat the later delegated admission context as authoritative. The controller answers through the normal permission APIs. This request has no `rememberKey`, so `always` is invalid; controllers use `once` or `reject`.
 
-Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` accepts `sessionId`, `sessionGenerationId`, `configurationRef`, and `title`. A child inherits its parent's `configurationRef` and cannot resume under a different reference. Child sessions reject direct `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
+Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` accepts `sessionId`, `sessionGenerationId`, `configurationRef`, and `title`. A child inherits its parent's `configurationRef` and cannot resume under a different reference. Child sessions reject direct `continuePrompt()`, `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
 
 The parent tool part receives `childSessionId` as soon as the child is acquired, so a host can offer an authorized live transcript. A foreground call also adds the resolved child model to its part and returns bounded JSON:
 
@@ -706,7 +709,7 @@ Queue payloads, status records, and `prompt.*` queue events are process-local. T
 
 The reservation save is the admission point. A save failure produces no start events or active audit. If disposal begins while that save is in flight and the save commits, admission still resolves and its completion settles as cancelled; disposal waits for terminal finalization.
 
-`listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
+`listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. `getMessages()`, `listMessagePage()`, `getMessage()` and `getSessionView()` take `includeUndone: true` to also return the messages of undone turns, which a redo can bring back: they follow the visible messages in their place, each marked `undone: true`, and page indexes count them. `undone` is set only by such a read and never stored. Messages a committed branch removed are gone and no read returns them. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
 
 `updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Every session exposes `preview` once a run with prompt text was admitted: its first prompt as one line (whitespace runs collapsed, cut at a character boundary to `maxTitleBytes`), with no model call, so a host can name a session nobody titled (`title || preview`). It is set once, a session stored before previews existed takes it from its first prompt at its next run, and no caller sets or clears it. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
 
@@ -714,6 +717,55 @@ The reservation save is the admission point. A save failure produces no start ev
 
 `abort()` returns `true` only while cancellation is still accepted. Terminal persistence is the run's commit point; once it starts, `abort()` returns `false` and the already-fixed terminal outcome completes while the session remains busy.
 
+### Continuing Without New Input
+
+Use `continuePrompt()` after a failed or stopped run whose input remains in context
+(`keptInContext: true`), when the conversation still needs an answer:
+
+```typescript
+const continuation = await harness.continuePrompt(scopeId, sessionId, {
+  modelHint: 'available-model',
+});
+console.log(continuation.queueId);
+const result = await continuation.completion;
+console.log(result.assistantMessage.parts);
+```
+
+The signature is `continuePrompt(scopeId: string, sessionId: string,
+options?: IFlexContinuePromptOptions): Promise<IFlexPromptQueueAdmission<IFlexContinuePromptResult>>`.
+It accepts `modelHint`, `system`, `maxSteps` and initial `steers`, plus optional
+`scheduleKey` and `debounceMs` for the same scheduling behavior as `schedulePrompt()`.
+`debounceMs` requires a schedule key and defaults to 50 ms when scheduled. There is
+no `prompt` or `promptId`: continuation creates a new run and an assistant message
+without appending or modifying a user message. Its result has the prompt result's
+fields except `userMessage`. Explicit steers still become user messages normally.
+
+Admission returns `{ queueId, completion }` once queued, like `enqueuePrompt()`.
+The entry and its `prompt.*` events carry `continuation: true`. Inspect its `runId`
+after `prompt.started`, or read it through `getPromptQueueEntry()`. Use the same
+`cancelPrompt()`, `cancelScheduledPrompt()`, `abort()` and `steerPrompt()` methods.
+Queue bounds and FIFO order, permissions, resource cleanup, compaction, usage
+accounting and provider limits follow the ordinary run path.
+
+At the front of the FIFO, the harness validates the visible transcript and model
+context with undone and excluded runs filtered out, before committing an undone
+branch or reserving a generation or audit message. A refusal preserves redo history.
+Empty context, an already answered turn, and an unsuccessful input that did not stay
+in context refuse with `FlexHarnessValidationError` through `completion`. A retained
+failure whose model context ends in partial assistant text with no tool call is also
+refused; `keptInContext: true` alone does not guarantee it can be continued. An earlier
+queued answer can therefore invalidate a waiting continuation. Cancellation before
+execution leaves the retained input available for another continuation. Continuing never replays
+previous tool calls; unknown external effects still require reconciliation.
+
+Existing projections and Agent event stores remain readable without migration.
+Assistant-only runs require two optional fields in the existing schema-3 projection:
+a staged terminal omits `userMessage`, and its reversion segment omits
+`userMessageId`. Requiring either would invent a user message. Generation claims
+use existing events without a new `user-message` event. Older strict projection
+readers cannot open a session containing these continuation records; do not mix
+versions or downgrade those sessions.
+
 ### Steering a Running Turn
 
 `steerPrompt()` hands a message to the running run of a prompt instead of queueing it behind that run:
@@ -734,6 +786,8 @@ The run takes a steer in at its next step boundary: after the tool results of it
 
 A prompt can bring further user messages into its run: `startPrompt()`, `enqueuePrompt()` and `prompt()` take `steers`, a list of `{ steerId, prompt }`, in their options. The run accepts them when it starts, emitting `prompt.steer.accepted` for each in the given order right after `prompt.started`, and takes them in before its first model call, so the model sees the prompt and its steers as consecutive user messages of their own in one call, each with its own `steerId`, `messageId` and attachments. From then on they report like every other steer of the run. They count against the session's outstanding prompt limits from admission on. The whole prompt is refused with `FlexHarnessValidationError` when a `steerId` repeats, and with `FlexHarnessQueueFullError` when it brings more steers than `maxOutstandingPromptsPerSession` or its steers' bytes exceed the outstanding byte limit. A prompt cancelled before its run started lists them in `unappliedSteerIds` on its finished queue entry and `prompt.finished`, with `keptInContext: false`. A caller holding several waiting messages for a session delivers them in one turn this way, without merging them into one message.
 
+A prompt can name itself with `promptId` in its options (`startPrompt()`, `enqueuePrompt()`, `prompt()` and `schedulePrompt()`): a non-empty string of at most 512 UTF-8 bytes, validated like a `steerId`. It is on the prompt's queue entry and its queue events, and on the user message that heads its run, also after a restart, so a caller that is unsure whether a prompt was taken in finds out from the transcript. A prompt whose `promptId` an outstanding prompt of the same session, queued or running, already holds is refused with `FlexHarnessDuplicatePromptError`; once that prompt finished, the id is free again. Other sessions' prompts do not count.
+
 ### 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:
@@ -812,7 +866,7 @@ At most 128 custom commands may be registered. Every registration must be a plai
 
 `/undo` and `/redo`, plus `undoSession()` and `redoSession()`, move a durable history cursor. The direct methods return `{ revertedRunId }` and `{ restoredRunId }`; the slash forms return `{ type: 'operation', name: 'undo' | 'redo' }`. Each committed cursor move emits one `session.history.changed` event with `direction`, `runId`, and the selected session identity. A committed branch emits the same event with `direction: 'branch'` and no `runId`, so controllers should refresh the complete selected session. Capture finalization, cleanup, and metadata-only changes do not emit this event.
 
-A completed root-session turn defines an operation-group boundary. Failed and cancelled turns after it belong to that group; leading failed or cancelled turns belong to the first completed group. No completed boundary means there is nothing to undo; retained leading unsuccessful history is grouped with the next completed turn rather than silently discarded. Undo hides that group's canonical partial history and outcome markers as well as its visible messages, redo restores them, and branching keeps the hidden history excluded. Transcript-only undo never claims to reverse external tool effects. Undo applies selected segments in reverse order and redo applies them in forward order. Without `turnReversionProvider`, only transcript and future model context move. Hidden messages disappear from `getMessages()`, message pages, exact message lookup, and future model context. Starting a new prompt, template, handler, or compaction from an undone position commits a branch: hidden messages and segments are removed durably and cannot be redone. Successful event archival also commits hidden redo history; a missing compaction or failed archive leaves it intact. Automatic budget compaction archives covered events after generation finalization and advances the same undo horizon; set `contextCompactionBytes: false` to disable that automatic policy.
+A completed root-session turn defines an operation-group boundary. Failed and cancelled turns after it belong to that group; leading failed or cancelled turns belong to the first completed group. No completed boundary means there is nothing to undo; retained leading unsuccessful history is grouped with the next completed turn rather than silently discarded. Undo hides that group's canonical partial history and outcome markers as well as its visible messages, redo restores them, and branching keeps the hidden history excluded. Transcript-only undo never claims to reverse external tool effects. Undo applies selected segments in reverse order and redo applies them in forward order. Without `turnReversionProvider`, only transcript and future model context move. Hidden messages disappear from `getMessages()`, message pages, exact message lookup, and future model context. Starting a new prompt, template, handler, or compaction from an undone position commits a branch: hidden messages and segments are removed durably and cannot be redone. Successful event archival also commits hidden redo history; a missing compaction or failed archive leaves it intact. Automatic budget compaction archives covered events after generation finalization and advances the same undo horizon; `contextCompaction: false` turns budget compaction off.
 
 Two horizons bound undo. Retention pruning removes the oldest complete visible units when `reversionLimits` is exceeded. Explicit event archival marks covered turns context-unavailable and prunes complete prefixes that can no longer be rebuilt; FlexHarness never crosses that archive horizon. Manual compaction without archival retains the original events and remains undoable. Schema-1 projection history and sessions migrated from `2.x` have no reversion segments, so historical turns are not retroactively undoable; newly written turns are tracked normally.
 
@@ -950,7 +1004,7 @@ The model context is built by the session's canonical AgentSession event history
 2. The normalized current user message.
 3. AgentSession's result messages.
 
-A failed or cancelled prompt remains visible through `getMessages()` with its truthful `failed` or `cancelled` status. Its canonical partial history also remains in future model context when execution produced output; an unsuccessful generation without output is omitted. Retention is not acceptance and does not roll back or replay external effects. Canonical Agent events remain private and are not exposed by the session or message APIs.
+A failed or cancelled prompt remains visible through `getMessages()` with its truthful `failed` or `cancelled` status. Its canonical partial history also remains in future model context when execution produced output; an unsuccessful generation without output is omitted. Each user message, the prompt and every steer its run took in, carries `keptInContext` once its run reached its terminal state: the run's `keptInContext`, true when the run's result kept the message in the model context of later turns, false when it did not, as for an unsuccessful run without model or tool output; a failed or stopped run that produced output stays in context and reports true. It records that outcome and is never rewritten: a later undo is reported by `undone` on an `includeUndone` read, and a later compaction summarizes the message, which was still delivered. A message whose run has not ended carries none, and neither do messages written before FlexHarness 15.0.0. Retention is not acceptance and does not roll back or replay external effects. Canonical Agent events remain private and are not exposed by the session or message APIs.
 
 Resolved model identity contains provider and model IDs plus optional display name and effective `variant`. The identity, including its variant, is attached to a failed assistant message when resolution completed before a later failure, matching the provider/model behavior. Prompt results contain it only on success.
 
@@ -1005,7 +1059,7 @@ if (started.status === 'started') {
 
 **Read-only.** An imported session never runs, and nothing writes model context for it: it has no Agent events and no tool jobs. Every operation that would change its history or model context throws `FlexHarnessImportedSessionError` (code `FLEX_SESSION_READ_ONLY`):
 
-- `prompt`, `startPrompt`, `enqueuePrompt` and `schedulePrompt`;
+- `prompt`, `startPrompt`, `enqueuePrompt`, `schedulePrompt` and `continuePrompt`;
 - `executeSlashCommand` and `compactSession`;
 - `undoSession` and `redoSession`;
 - `pushRuntimeEvent`, `reconcileToolExecution` and `archiveSessionEvents`;
@@ -1082,6 +1136,21 @@ Transactional tool calls persist an execution intent before the tool side effect
 
 `executionContextProvider` can construct a AgentSession execution context for each session. FlexHarness supplies the resolved scope, storage key, and the session's private job store. The public background APIs expose only execution ID, type, state, exit code, and timestamps; command payloads, stdout, and stderr remain private. The provider's optional `close()` is owned by session deletion, scope retirement, and harness disposal.
 
+### Compaction Point
+
+With a compactor, a generation compacts settled history before its first inference once the session's context reaches its compaction point, in tokens of the run's model. The point never exceeds its ceiling: 90% of the model's served context window, which the model resolver states as `IFlexResolvedModel.contextWindow`. That is the window the provider serves by default, never an extended maximum: a Codex catalog's `context_window`, not its `max_context_window`; Anthropic's Models API `max_input_tokens`, where 1M is the default window of the 1M-token models without any beta header. By default the point is the ceiling, or the catalog's own automatic compaction point when it states a lower one (`IFlexResolvedModel.contextCompactionDefaultTokens`, a Codex catalog's `auto_compact_token_limit`). A session chooses its own point with `contextCompaction` on `createSession()` or `updateSession()`, where `null` returns it to the default; `agentSessionPolicy.contextCompaction` is the default for sessions without one.
+
+| `contextCompaction` | Compaction point |
+| --- | --- |
+| omitted | The model's default; none when the model states no served window |
+| `{ tokens }` | The count, clamped at run time to the ceiling of the run's model; unclamped when the model states no served window |
+| `{ percent }` | An integer from 1 through 90 of the served window; none when the model states none |
+| `false` | None |
+
+A percent outside 1 through 90, a token count that is not a positive integer, or a setting other than `false` on a harness without a `contextCompactor` is rejected with `FlexHarnessValidationError`. `getSessionMetrics()` states the last settled run's `contextWindow` and either its `contextCompactionTokens` or, when it had none, `contextCompactionOff`: `disabled`, `no-context-window` or `no-compactor`. A changed setting shows there from the next run; `resolveAgentContextCompactionPoint({ contextWindow, contextCompactionDefaultTokens, setting })` states the point a session would have on a model before any run.
+
+The context is measured with the provider's own count where there is one. Each transactional generation's outcome event carries `contextUsage`: the input tokens its last model call reported, with the events that call saw. The reading counts while those events still build the same model messages and no compaction followed them; what was committed after it is estimated at 4 UTF-8 JSON bytes per token. After a compaction, an undo or a branch, and for history written before readings existed, the whole context is estimated that way. The check runs once per generation, before its first inference: a generation that grows past the point in its own tool loop is compacted only when its context overflows.
+
 ### Context Compaction Model
 
 A `contextCompactor` states which model to compact with from the model the compacted work was dispatched on, never from a host default that may name another account:
@@ -1089,7 +1158,7 @@ A `contextCompactor` states which model to compact with from the model the compa
 | `reason` | Compaction | Model members |
 | --- | --- | --- |
 | `context-overflow` | A run's context overflowed, including a delegated run's | `resolvedModel`: the `IFlexResolvedModel` the model resolver returned for that run, frozen; a delegated run's overflow carries the delegated run's own model |
-| `context-budget` | Settled history exceeds `contextCompactionBytes` before a generation's first inference (256 KiB by default with a compactor) | `resolvedModel`: the exact model resolved for that run, including its delegated model |
+| `context-budget` | The context reaches the session's compaction point before a generation's first inference; see Compaction Point | `resolvedModel`: the exact model resolved for that run, including its delegated model |
 | `manual` | `/compact` or `compactSession()` | `modelHint`: the `modelHint` of the `/compact` execution options or of `compactSession(scopeId, sessionId, { modelHint })`, when one was passed |
 | `retention` | Event retention | none |
 

package/ts/utils.harnessoptions.ts

@@ -33,7 +33,7 @@ import {
   isReservedSlashCommandName,
   isValidSlashCommandName,
 } from './utils.slashcommands.js';
-import { validateUtf8String } from './utils.validation.js';
+import { validateContextCompactionSetting, validateUtf8String } from './utils.validation.js';
 
 export type TRegisteredSlashCommand<TScope> =
   | Readonly<IFlexSlashCommandTemplateRegistration>
@@ -548,10 +548,17 @@ export function resolveResultLimits(
 export function normalizeAgentSessionPolicy<TScope>(
   policy: IFlexAgentSessionPolicy<TScope> = {},
 ): IFlexAgentSessionPolicy<TScope> {
+  if (policy.contextCompaction !== undefined) {
+    validateContextCompactionSetting(
+      policy.contextCompaction,
+      policy.contextCompactor !== undefined,
+      'agentSessionPolicy.contextCompaction',
+    );
+  }
   return {
     ...(policy.contextBuilder === undefined ? {} : { contextBuilder: policy.contextBuilder }),
     ...(policy.contextCompactor === undefined ? {} : { contextCompactor: policy.contextCompactor }),
-    ...(policy.contextCompactionBytes === undefined ? {} : { contextCompactionBytes: policy.contextCompactionBytes }),
+    ...(policy.contextCompaction === undefined ? {} : { contextCompaction: policy.contextCompaction }),
     ...(policy.eventRetention === undefined ? {} : { eventRetention: policy.eventRetention }),
     ...(policy.changeListenerTimeoutMs === undefined
       ? {}