@modelprofile.com/flexharness-agent 9.9.1 → 10.0.0

package/ts_agent/classes.sessionengine.ts

@@ -20,8 +20,13 @@ import {
   type IUserMessageEvent,
   type TAgentEvent,
   type TAgentGenerationOutcome,
+  type TAgentToolCallPart,
   type TAgentToolResultOutput,
 } from './smartagent.events.js';
+import type {
+  AgentPendingInputQueue,
+  IAgentAppliedInput,
+} from './smartagent.pendinginput.js';
 import {
   AgentGenerationLeaseCleanupError,
   ContextOverflowError,
@@ -31,6 +36,7 @@ import {
   type IAgentGenerationLease,
   type IAgentCompactOptions,
   type IAgentBeginGenerationOptions,
+  type IAgentFinalizeGenerationOptions,
   type IAgentSession,
   type IAgentSessionAbortOptions,
   type IAgentSessionChange,
@@ -101,8 +107,11 @@ interface IScheduledGeneration {
   cache?: TAgentCacheSetting;
   maxSteps?: number;
   abort?: AbortSignal;
+  stop?: AbortSignal;
   transaction?: IAgentGenerationHandle;
   prepare?: TAgentGenerationPrepare;
+  pendingInput?: AgentPendingInputQueue;
+  onInputApplied?: (input: IAgentAppliedInput) => void | Promise<void>;
   timer: NodeJS.Timeout;
   controller: AbortController;
   removeAbortListener: () => void;
@@ -316,6 +325,7 @@ export class AgentSessionEngine implements IAgentSession {
   private sequence = 0;
   private persistenceRevision = 0;
   private persistenceQueue: Promise<void> = Promise.resolve();
+  private pendingPersistence?: { snapshot: TAgentEvent[]; task: Promise<void> };
   private persistenceError: unknown;
   private readonly notificationDispatches = new Set<Promise<void>>();
   private readonly listeners = new Map<TAgentSessionChangeListener, IAgentSessionListenerState>();
@@ -401,6 +411,14 @@ export class AgentSessionEngine implements IAgentSession {
     if (!Number.isSafeInteger(maxContextOverflowRetries) || maxContextOverflowRetries < 0) {
       throw new Error('maxContextOverflowRetries must be a non-negative integer.');
     }
+    if (options.contextCompactionBytes !== undefined && options.contextCompactionBytes !== false
+      && (!Number.isSafeInteger(options.contextCompactionBytes)
+        || options.contextCompactionBytes < 1 || options.contextCompactionBytes > 32 * 1024 * 1024)) {
+      throw new Error('contextCompactionBytes must be false or an integer from 1 through 33554432.');
+    }
+    if (typeof options.contextCompactionBytes === 'number' && !options.contextCompactor) {
+      throw new Error('contextCompactionBytes requires a contextCompactor.');
+    }
     const changeListenerTimeoutMs = options.changeListenerTimeoutMs ?? 30_000;
     if (!Number.isSafeInteger(changeListenerTimeoutMs) || changeListenerTimeoutMs <= 0) {
       throw new Error('changeListenerTimeoutMs must be a positive integer.');
@@ -500,14 +518,24 @@ export class AgentSessionEngine implements IAgentSession {
   private queuePersistence(): Promise<void> {
     if (!this.options.eventStore) return Promise.resolve();
     const snapshot = structuredClone(this.events);
+    if (this.pendingPersistence) {
+      this.pendingPersistence.snapshot = snapshot;
+      return this.pendingPersistence.task;
+    }
+    let pending: NonNullable<AgentSessionEngine['pendingPersistence']>;
     const operation = this.persistenceQueue.then(async () => {
+      if (this.pendingPersistence === pending) this.pendingPersistence = undefined;
       if (this.persistenceError !== undefined) throw this.persistenceError;
       this.persistenceRevision = await this.options.eventStore!.save(
         this.options.sessionId!,
-        snapshot,
+        pending.snapshot,
         this.persistenceRevision,
       );
     });
+    // One durable snapshot covers every commit queued before this write begins. In-flight snapshots
+    // stay immutable, and callers still wait for the write that contains their event.
+    pending = { snapshot, task: operation };
+    this.pendingPersistence = pending;
     this.persistenceQueue = operation.catch((error) => {
       this.persistenceError ??= error;
     });
@@ -821,6 +849,7 @@ export class AgentSessionEngine implements IAgentSession {
     generationId: string,
     outcome: TAgentGenerationOutcome,
     reason?: string,
+    stopped = false,
   ): Promise<void> {
     const transaction = this.transaction(generationId);
     if (
@@ -853,6 +882,7 @@ export class AgentSessionEngine implements IAgentSession {
       generationId,
       outcome,
       reason,
+      ...(stopped ? { stopped: true } : {}),
       parentIds: [parent.id],
     }));
     await this.flushPersistence();
@@ -874,6 +904,7 @@ export class AgentSessionEngine implements IAgentSession {
   public finalizeGeneration(
     transaction: IAgentGenerationHandle,
     outcome: TAgentGenerationOutcome,
+    options: IAgentFinalizeGenerationOptions = {},
   ): Promise<void> {
     const capabilityError = this.transactionalStoreCapabilityError();
     if (capabilityError) return Promise.reject(capabilityError);
@@ -881,6 +912,9 @@ export class AgentSessionEngine implements IAgentSession {
       if (!['accepted', 'rejected', 'interrupted'].includes(outcome)) {
         throw new Error(`Invalid transactional generation outcome "${String(outcome)}".`);
       }
+      if (options.stopped === true && outcome !== 'interrupted') {
+        throw new Error('Only an interrupted transactional generation can be stopped.');
+      }
       const state = this.verifyGenerationClaim(transaction);
       if (!('begun' in state)) {
         if (state.outcome === outcome) return;
@@ -888,7 +922,24 @@ export class AgentSessionEngine implements IAgentSession {
           `Transactional generation "${transaction.generationId}" already has outcome "${state.outcome}".`,
         );
       }
-      await this.appendGenerationOutcome(transaction.generationId, outcome);
+      await this.appendGenerationOutcome(
+        transaction.generationId,
+        outcome,
+        undefined,
+        options.stopped === true,
+      );
+      if (this.options.contextCompactor && this.options.contextCompactionBytes !== false
+        && this.options.eventStore?.archive
+        && getOpenAgentGenerationTransactions(this.events).length === 0
+        && getUncertainToolExecutionIntents(this.events).length === 0) {
+        const activeIds = new Set(this.events.map((event) => event.id));
+        for (const event of [...this.events]) {
+          if (event.type === 'context-compaction' && event.automatic
+            && event.coveredEventIds.some((id) => activeIds.has(id))) {
+            await this.archiveCompactedEventsLocked(event.id);
+          }
+        }
+      }
     });
   }
 
@@ -1024,6 +1075,9 @@ export class AgentSessionEngine implements IAgentSession {
       ? this.transactionalStoreCapabilityError()
       : undefined;
     if (capabilityError) return Promise.reject(capabilityError);
+    if (options.stop && !options.transaction) {
+      return Promise.reject(new Error('A stop signal requires a transactional generation.'));
+    }
     if (!options.key.trim()) return Promise.reject(new Error('Scheduled generation key must not be empty.'));
     const debounceMs = options.debounceMs ?? 50;
     if (!Number.isSafeInteger(debounceMs) || debounceMs < 0) {
@@ -1039,7 +1093,10 @@ export class AgentSessionEngine implements IAgentSession {
         || existing.cache !== options.cache
         || existing.maxSteps !== options.maxSteps
         || existing.abort !== options.abort
+        || existing.stop !== options.stop
         || existing.prepare !== options.prepare
+        || existing.pendingInput !== options.pendingInput
+        || existing.onInputApplied !== options.onInputApplied
         || existing.transaction?.generationId !== options.transaction?.generationId
         || existing.transaction?.claimToken !== options.transaction?.claimToken
       ) {
@@ -1053,8 +1110,9 @@ export class AgentSessionEngine implements IAgentSession {
       return existing.promise;
     }
 
-    if (options.abort?.aborted) {
-      const abortReason = options.abort.reason ?? new DOMException('Aborted', 'AbortError');
+    const endedBy = options.abort?.aborted ? options.abort : options.stop?.aborted ? options.stop : undefined;
+    if (endedBy) {
+      const abortReason = endedBy.reason ?? new DOMException('Aborted', 'AbortError');
       if (!options.transaction) return Promise.reject(abortReason);
       return this.queueExclusive(async () => {
         const transaction = this.verifyGenerationClaim(options.transaction!);
@@ -1082,9 +1140,11 @@ export class AgentSessionEngine implements IAgentSession {
     const controller = new AbortController();
     const onAbort = () => this.cancelScheduledGeneration(
       options.key,
-      options.abort?.reason ?? new DOMException('Aborted', 'AbortError'),
+      (options.abort?.aborted ? options.abort.reason : options.stop?.reason)
+        ?? new DOMException('Aborted', 'AbortError'),
     );
     options.abort?.addEventListener('abort', onAbort, { once: true });
+    options.stop?.addEventListener('abort', onAbort, { once: true });
     const scheduled: IScheduledGeneration = {
       state: 'debouncing',
       debounceMs,
@@ -1095,11 +1155,17 @@ export class AgentSessionEngine implements IAgentSession {
       cache: options.cache,
       maxSteps: options.maxSteps,
       abort: options.abort,
+      stop: options.stop,
       transaction: options.transaction,
       prepare: options.prepare,
+      pendingInput: options.pendingInput,
+      onInputApplied: options.onInputApplied,
       timer: setTimeout(() => this.startScheduledGeneration(options.key), debounceMs),
       controller,
-      removeAbortListener: () => options.abort?.removeEventListener('abort', onAbort),
+      removeAbortListener: () => {
+        options.abort?.removeEventListener('abort', onAbort);
+        options.stop?.removeEventListener('abort', onAbort);
+      },
       promise,
       resolve,
       reject,
@@ -1120,8 +1186,11 @@ export class AgentSessionEngine implements IAgentSession {
       cache: scheduled.cache,
       maxSteps: scheduled.maxSteps,
       abort: scheduled.controller.signal,
+      stop: scheduled.stop,
       transaction: scheduled.transaction,
       prepare: scheduled.prepare,
+      pendingInput: scheduled.pendingInput,
+      onInputApplied: scheduled.onInputApplied,
     }).then(
       (result) => this.settleScheduledGeneration(key, scheduled, () => scheduled.resolve(result)),
       (error) => this.settleScheduledGeneration(key, scheduled, () => scheduled.reject(error)),
@@ -1149,6 +1218,7 @@ export class AgentSessionEngine implements IAgentSession {
     const cancellationReason = reason
       ?? new DOMException('Scheduled generation cancelled', 'AbortError');
     if (!scheduled.controller.signal.aborted) scheduled.controller.abort(cancellationReason);
+    scheduled.pendingInput?.close();
     if (!scheduled.transaction) {
       scheduled.reject(cancellationReason);
       return true;
@@ -1180,7 +1250,7 @@ export class AgentSessionEngine implements IAgentSession {
   }
 
   private async performCompaction(
-    reason: 'context-overflow' | 'retention' | 'manual',
+    reason: 'context-overflow' | 'context-budget' | 'retention' | 'manual',
     reportUsage: TAgentModelCallUsageReporter,
     abortSignal?: AbortSignal,
   ): Promise<IContextCompactionEvent | undefined> {
@@ -1189,7 +1259,7 @@ export class AgentSessionEngine implements IAgentSession {
     abortSignal?.throwIfAborted();
     const unresolvedIntents = getUncertainToolExecutionIntents(this.events);
     if (unresolvedIntents.length > 0) {
-      if (reason === 'context-overflow' || reason === 'retention') return undefined;
+      if (reason === 'context-overflow' || reason === 'context-budget' || reason === 'retention') return undefined;
       throw new Error('Context compaction is blocked by unresolved tool execution intents.');
     }
     const openTransactions = getOpenAgentGenerationTransactions(this.events);
@@ -1199,7 +1269,7 @@ export class AgentSessionEngine implements IAgentSession {
     let coveredEvents: TAgentEvent[];
     if (openTransactions.length > 0) {
       if (reason === 'retention') return undefined;
-      if (reason !== 'context-overflow') {
+      if (reason !== 'context-overflow' && reason !== 'context-budget') {
         throw new Error('Context compaction is blocked while a transactional generation is open.');
       }
       const openGenerationIds = new Set(
@@ -1257,6 +1327,7 @@ export class AgentSessionEngine implements IAgentSession {
       .slice(-(this.options.maxArchivedTransactionTombstones ?? 1000));
     const compaction = this.commitEvent(createAgentEvent<IContextCompactionEvent>({
       type: 'context-compaction',
+      ...(reason === 'context-budget' ? { automatic: true as const } : {}),
       coveredEventIds: coveredEvents.map((event) => event.id),
       replacementEvents: modelMessagesToAgentEvents(replacementMessages),
       archivedTransactions: archivedTransactions.length > 0
@@ -1492,6 +1563,7 @@ export class AgentSessionEngine implements IAgentSession {
     preparationErrors: ReadonlyMap<string, unknown>,
     ledger: Map<string, IToolExecutionLedgerEntry>,
     getMessages: () => plugins.ModelMessage[],
+    onPreview: (event: IAgentToolCallUpdateEvent) => void,
   ): plugins.ToolSet {
     const wrappedTools: plugins.ToolSet = {};
     for (const [toolName, toolDefinition] of Object.entries(tools)) {
@@ -1551,6 +1623,7 @@ export class AgentSessionEngine implements IAgentSession {
                 result,
                 resolveCompletion,
                 rejectCompletion,
+                (output) => onPreview({ toolCallId, toolName, input, output }),
               );
             }
             if (isPromiseLike(result)) {
@@ -1566,6 +1639,7 @@ export class AgentSessionEngine implements IAgentSession {
                 deferredIterable,
                 resolveCompletion,
                 rejectCompletion,
+                (output) => onPreview({ toolCallId, toolName, input, output }),
               );
             }
             resolveCompletion(result);
@@ -1590,6 +1664,7 @@ export class AgentSessionEngine implements IAgentSession {
     iterable: AsyncIterable<unknown>,
     resolveCompletion: (output: unknown) => void,
     rejectCompletion: (error: unknown) => void,
+    onOutput: (output: unknown) => void,
   ): AsyncIterable<unknown> {
     const iterator = iterable[Symbol.asyncIterator]();
     let settled = false;
@@ -1621,7 +1696,11 @@ export class AgentSessionEngine implements IAgentSession {
       }
       return operationResult.then(
         (result) => {
-          if (!result.done && cacheOutput) lastOutput = result.value;
+          if (!result.done && cacheOutput) {
+            lastOutput = result.value;
+            try { onOutput(result.value); }
+            catch (error) { settleError(error); throw error; }
+          }
           if (result.done) {
             if (rejectWhenDone) settleError(incompleteError());
             else settleSuccess();
@@ -1720,6 +1799,9 @@ export class AgentSessionEngine implements IAgentSession {
       ? this.transactionalStoreCapabilityError()
       : undefined;
     if (capabilityError) return Promise.reject(capabilityError);
+    if (options.stop && !options.transaction) {
+      return Promise.reject(new Error('A stop signal requires a transactional generation.'));
+    }
     const run = this.generationQueue.then(async () => {
       if (!options.transaction) options.abort?.throwIfAborted();
       if (!options.transaction && this.sessionAbortController.signal.aborted) {
@@ -1730,6 +1812,9 @@ export class AgentSessionEngine implements IAgentSession {
       if (this.maintenanceError !== undefined) throw this.maintenanceError;
       await this.runEventRetentionLocked();
       return this.generateLocked(options);
+    }).finally(() => {
+      // The generation takes no further input; what it never took in stays with the queue.
+      options.pendingInput?.close();
     });
     this.generationQueue = run.then(() => undefined, () => undefined);
     // A transactional generation is not raced against its abort signal: it settles when its
@@ -1801,6 +1886,7 @@ export class AgentSessionEngine implements IAgentSession {
       this.sessionAbortController.signal,
       generationAbortController.signal,
       options.abort,
+      options.stop,
     ]);
 
     let lease: IAgentGenerationLease | undefined;
@@ -1842,6 +1928,7 @@ export class AgentSessionEngine implements IAgentSession {
       let attempt = 0;
       let retriedMs = 0;
       let contextOverflowRetries = 0;
+      let automaticCompactionChecked = false;
       let totalInput = 0;
       let totalOutput = 0;
       let totalCacheRead = 0;
@@ -1862,6 +1949,8 @@ export class AgentSessionEngine implements IAgentSession {
       const reportCompactionUsage: TAgentModelCallUsageReporter = (call) =>
         recordModelCallUsage({ ...call, source: 'compaction', generationId });
       let currentInferenceId: string | undefined;
+      /** Text the current inference streamed so far, kept if the inference is interrupted. */
+      let inferenceText = '';
       let latestInferenceVisibleIds = new Set(this.events.map((event) => event.id));
       const completedInferenceIds = new Set<string>();
       const reasoningTextById = new Map<string, string>();
@@ -1873,6 +1962,7 @@ export class AgentSessionEngine implements IAgentSession {
       const ledger = new Map<string, IToolExecutionLedgerEntry>();
       const executionIntentIds = new Map<string, string>();
       const preliminaryToolOutputs = new Map<string, IAgentToolCallUpdateEvent>();
+      const finishedToolCallIds = new Set<string>();
 
       const beginInference = async (): Promise<string> => {
         const marker = this.commitEvent(createAgentEvent<IRuntimeEvent>({
@@ -1889,10 +1979,90 @@ export class AgentSessionEngine implements IAgentSession {
             : undefined,
         }));
         currentInferenceId = marker.id;
+        inferenceText = '';
         latestInferenceVisibleIds = new Set(this.events.map((event) => event.id));
         await this.flushPersistence();
         return marker.id;
       };
+      const applyPendingInput = async (): Promise<void> => {
+        const inputs = options.pendingInput?.drain() ?? [];
+        if (inputs.length === 0) return;
+        const applied: IAgentAppliedInput[] = [];
+        try {
+          for (const input of inputs) {
+            const event = this.commitEvent(createAgentEvent<IUserMessageEvent>({
+              type: 'user-message',
+              content: input.content,
+              inputId: input.inputId,
+              generationId,
+              parentIds: this.events.length > 0
+                ? [this.events[this.events.length - 1].id]
+                : undefined,
+            }));
+            applied.push({
+              inputId: input.inputId,
+              eventId: event.id,
+              generationId,
+              completedSteps: stepCount,
+            });
+          }
+          await this.flushPersistence();
+        } catch (error) {
+          // Input that is not durable was not taken in: the queue returns it from close().
+          options.pendingInput!.restore(inputs);
+          throw error;
+        }
+        // Every durable input is reported, also when reporting an earlier one failed.
+        const callbackErrors: unknown[] = [];
+        for (const input of applied) {
+          try {
+            await this.invokeGenerationCallback(() => options.onInputApplied?.(input));
+          } catch (error) {
+            callbackErrors.push(error);
+          }
+        }
+        if (callbackErrors.length === 1) throw callbackErrors[0];
+        if (callbackErrors.length > 1) {
+          throw new AggregateError(callbackErrors, 'Reporting applied pending input failed.');
+        }
+      };
+      /**
+       * Keeps what a stopped inference produced: the text it streamed and the tool calls it
+       * issued, as one assistant message of the generation. Tool calls without a result are
+       * closed when the stopped generation is rendered for the model.
+       */
+      const commitInterruptedInference = async (): Promise<void> => {
+        const inferenceId = currentInferenceId;
+        if (!options.stop?.aborted || !inferenceId || completedInferenceIds.has(inferenceId)) return;
+        completedInferenceIds.add(inferenceId);
+        if (this.events.some((event) =>
+          event.type === 'assistant-message' && event.inferenceId === inferenceId)) return;
+        const toolCallParts: TAgentToolCallPart[] = this.events
+          .filter((event): event is IToolCallEvent =>
+            event.type === 'tool-call'
+            && event.generationId === generationId
+            && event.inferenceId === inferenceId)
+          .map((event) => ({
+            type: 'tool-call',
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            input: event.input,
+            ...(event.providerExecuted === undefined ? {} : { providerExecuted: event.providerExecuted }),
+            ...(event.providerOptions === undefined ? {} : { providerOptions: event.providerOptions }),
+          }));
+        if (!inferenceText && toolCallParts.length === 0) return;
+        this.commitEvent(createAgentEvent<IAssistantMessageEvent>({
+          type: 'assistant-message',
+          content: [
+            ...(inferenceText ? [{ type: 'text' as const, text: inferenceText }] : []),
+            ...toolCallParts,
+          ],
+          generationId,
+          inferenceId,
+          causationId: inferenceId,
+        }));
+        await this.flushPersistence();
+      };
       const allTools = this.wrapToolsForGeneration(
         generationId,
         runtime.tools,
@@ -1901,6 +2071,13 @@ export class AgentSessionEngine implements IAgentSession {
         preparationErrors,
         ledger,
         () => this.buildContext(this.eventsByIds(latestInferenceVisibleIds)),
+        (event) => {
+          const previous = preliminaryToolOutputs.get(event.toolCallId);
+          if (!previous || !this.platform.isDeepEqual(previous.output, event.output)) {
+            preliminaryToolOutputs.set(event.toolCallId, event);
+            this.options.onToolCallUpdate?.(event);
+          }
+        },
       );
 
       const flushReasoning = (): void => {
@@ -1918,6 +2095,7 @@ export class AgentSessionEngine implements IAgentSession {
         let streamError: unknown;
         try {
           currentInferenceId = undefined;
+          inferenceText = '';
           const result = plugins.streamText({
             model: runtime.model,
             instructions: runtime.system,
@@ -1929,6 +2107,15 @@ export class AgentSessionEngine implements IAgentSession {
             maxRetries: 0,
             abortSignal: combinedAbort.signal,
             prepareStep: async () => {
+              await applyPendingInput();
+              if (!automaticCompactionChecked && this.options.contextCompactor
+                && this.options.contextCompactionBytes !== false) {
+                automaticCompactionChecked = true;
+                const bytes = new TextEncoder().encode(JSON.stringify(this.getModelMessages())).byteLength;
+                if (bytes > (this.options.contextCompactionBytes ?? 256 * 1024)) {
+                  await this.performCompaction('context-budget', reportCompactionUsage, combinedAbort.signal);
+                }
+              }
               await beginInference();
               return { messages: this.buildContext(this.eventsByIds(latestInferenceVisibleIds)) };
             },
@@ -1959,7 +2146,9 @@ export class AgentSessionEngine implements IAgentSession {
               const chunkType = String((chunk as { type?: unknown }).type ?? '');
               if (chunkType === 'text-delta') {
                 const textChunk = chunk as { delta?: string; textDelta?: string; text?: string };
-                this.options.onToken?.(textChunk.delta ?? textChunk.textDelta ?? textChunk.text ?? '');
+                const delta = textChunk.delta ?? textChunk.textDelta ?? textChunk.text ?? '';
+                inferenceText += delta;
+                this.options.onToken?.(delta);
                 return;
               }
               if (chunkType === 'tool-result') {
@@ -1971,6 +2160,10 @@ export class AgentSessionEngine implements IAgentSession {
                   output: unknown;
                 };
                 if (toolResultChunk.preliminary === true) {
+                  // Locally executed previews are delivered at the iterator boundary, not from
+                  // this independently backpressured SDK stream, which may arrive after finish.
+                  if (ledger.has(toolResultChunk.toolCallId)) return;
+                  if (finishedToolCallIds.has(toolResultChunk.toolCallId)) return;
                   const previous = preliminaryToolOutputs.get(toolResultChunk.toolCallId);
                   if (!previous || !this.platform.isDeepEqual(previous.output, toolResultChunk.output)) {
                     const event: IAgentToolCallUpdateEvent = {
@@ -2102,6 +2295,7 @@ export class AgentSessionEngine implements IAgentSession {
               return promise;
             },
             onToolExecutionEnd: async (finish) => {
+              finishedToolCallIds.add(finish.toolCall.toolCallId);
               preliminaryToolOutputs.delete(finish.toolCall.toolCallId);
               const inferenceId = currentInferenceId ?? await beginInference();
               const previousResult = this.currentGenerationEvent(
@@ -2245,8 +2439,11 @@ export class AgentSessionEngine implements IAgentSession {
           flushReasoning();
           const effectiveError = streamError ?? error;
           if (combinedAbort.signal.aborted) {
+            await commitInterruptedInference();
             throw combinedAbort.signal.reason ?? new DOMException('Aborted', 'AbortError');
           }
+          // A failed attempt is retried or fails the generation; its partial text is not kept.
+          inferenceText = '';
           if (effectiveError instanceof DOMException && effectiveError.name === 'AbortError') {
             throw effectiveError;
           }
@@ -2344,6 +2541,7 @@ export class AgentSessionEngine implements IAgentSession {
                 generationId,
                 'interrupted',
                 this.transactionOutcomeErrorReason(effectiveError),
+                options.stop?.aborted === true,
               );
             } else {
               const transaction = this.transaction(generationId);
@@ -2366,6 +2564,7 @@ export class AgentSessionEngine implements IAgentSession {
                   generationId,
                   'interrupted',
                   this.transactionOutcomeErrorReason(abortError),
+                  options.stop?.aborted === true,
                 );
                 throw abortError;
               }

package/ts_agent/index.ts

@@ -6,6 +6,7 @@ export {
   getAgentGenerationTransactions,
   getOpenAgentGenerationTransactions,
   getUncertainToolExecutionIntents,
+  isGenerationInModelContext,
   isTransactionalGeneration,
 } from './smartagent.transactions.js';
 export {
@@ -13,6 +14,15 @@ export {
   createAgentEventId,
   modelMessagesToAgentEvents,
 } from './smartagent.events.js';
+export {
+  AgentPendingInputQueue,
+  AgentPendingInputRejectedError,
+} from './smartagent.pendinginput.js';
+export type {
+  IAgentAppliedInput,
+  IAgentPendingInput,
+  TAgentPendingInputRejection,
+} from './smartagent.pendinginput.js';
 export { ToolRegistry } from './smartagent.classes.toolregistry.js';
 export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
 export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
@@ -35,6 +45,7 @@ export type {
   IAgentCompactOptions,
   IAgentEventRetentionOptions,
   IAgentBeginGenerationOptions,
+  IAgentFinalizeGenerationOptions,
   IAgentGenerateOptions,
   IAgentGenerateResult,
   IAgentGenerationHandle,

package/ts_agent/readme.md

@@ -274,10 +274,34 @@ export async function createReviewedDraft(
 
 The `review` callback belongs to your application. While awaiting acceptance, `candidate.messages` includes the candidate, but `getModelMessages()` excludes it from ordinary future context. Acceptance includes the generation; rejection keeps it in the canonical event history while excluding it from future context. Generation IDs identify transactions within a session; use a distinct ID for each new transaction.
 
+`generate({ transaction, stop })` takes a second signal for the owner's stop, the way a user stops a turn. It ends the generation like `abort`, but the interrupted outcome records the stop (`stopped: true`, also accepted by `finalizeGeneration(transaction, 'interrupted', { stopped: true })` for a generation stopped after its execution completed). A stopped generation stays in future context once its model produced output: its prompt, the input it took in, the text its running model step streamed and the tool calls it issued. Each tool call without a recorded result is closed with an error result saying its effect is unknown, so the next request is well-formed for every provider. A generation stopped before any model output leaves no trace, so its prompt can be sent again without appearing twice. `isGenerationInModelContext(events, generationId)` applies the same rule to a list of events, for a caller that needs to know whether a finished generation stayed in context. Aborted and failed generations, and generations a restart interrupted, stay out of future context as before. `stop` requires a transactional generation.
+
 Closing a session or restoring a stored session interrupts unfinished transactions. Restoration does not automatically rerun them. Persisted transactions require an `IAgentEventStoreV2` store with `eventSchemaVersion: 2`; without a store, transactions are process-local.
 
 A rejected generation does not roll back external tool effects. The runtime records transactional tool-execution intents and results. If a crash leaves an intent without a known result, inspect `listUncertainToolExecutions()` and reconcile the external operation through `reconcileToolExecution()` before treating its outcome as known. This is not a general exactly-once guarantee for external services.
 
+## Take input while a generation runs
+
+Pass an `AgentPendingInputQueue` to `generate({ pendingInput })` to let the user steer a running generation. The generation takes waiting input in at every step boundary, after the tool results of the previous model step are recorded and before the next model call, and records each input as a user message of the generation (`inputId` set). A running tool call is never interrupted. `onInputApplied` is called for each input once it is durable, before the next model call; every durable input is reported, also when reporting an earlier one throws, and the generation then fails with that error. Input the generation could not record durably counts as never taken in: the generation gives it back to the queue with `restore()`.
+
+```typescript
+import { AgentPendingInputQueue } from '@modelprofile.com/flexharness-agent';
+
+const pendingInput = new AgentPendingInputQueue();
+const transaction = await session.beginGeneration('Plan the release.');
+const generation = session.generate({
+  transaction,
+  pendingInput,
+  onInputApplied: ({ inputId, eventId }) => markApplied(inputId, eventId),
+});
+// While the generation runs:
+pendingInput.add({ inputId: 'steer-1', content: 'Keep the migration out of it.' });
+await generation;
+const unapplied = pendingInput.close(); // input the generation never took in
+```
+
+The generation closes the queue when it ends, whether it completed, failed or was aborted. `close()` returns the inputs it never took in, the same list on every call once the generation has ended; input that arrives during the last model step is among them, and so is input the generation drained but could not record durably. After closing, `add()` throws `AgentPendingInputRejectedError` with reason `closed`, and a reused `inputId` is refused with reason `duplicate`. The caller decides what becomes of unapplied input, for example sending it as the next turn.
+
 ## Events, storage and context
 
 Canonical events retain user and assistant messages, tool calls and results, runtime events, compaction records and transaction outcomes. `getEvents()` returns this history; `getModelMessages()` projects the model-visible conversation through the configured `contextBuilder`, which defaults to `buildModelMessages`.
@@ -297,12 +321,15 @@ export function openStoredSession(eventStore: IAgentEventStoreV2, sessionId: str
 
 Use an application-owned durable adapter for persistent sessions. Its `save(sessionId, events, expectedRevision)` must atomically compare the revision and return the new revision, or reject a conflict. Preserve the schema and supported values in canonical events; the package exports schema validators and `AgentEventStoreConflictError` for adapter implementations. Keep one active owner per session; compare-and-swap detects conflicting writes rather than merging competing sessions.
 
+Commits queued before a save starts share one durable snapshot containing them all. An in-flight snapshot is immutable, and every caller and change notification still waits for the save containing its event. The adapter's revision advances per durable snapshot, not necessarily per event.
+
 `InMemoryAgentEventStore` is useful for tests and sessions that only need process-local storage. The Node root also exports the explicit `FileAgentEventStore` adapter. Neither storage selection nor a durable backend is implicit.
 
 ### Bound model context and active events
 
 - `contextBuilder({ events })` controls the model-message projection.
 - `contextCompactor(messages, events, { reason, abortSignal, reportUsage })` returns replacement model messages. Provide it to use `session.compact()` or automatic event retention. Report the usage of its model calls through `reportUsage`; see [What is counted](#what-is-counted).
+- A compactor also enables proactive compaction with reason `context-budget` before inference. `contextCompactionBytes` defaults to 256 KiB of UTF-8 JSON model messages, accepts 1 through 32 MiB, and may be `false` to disable it. Only settled history is covered, never the current unsettled generation. Budget compactions carry `automatic: true`; after transactional finalization their covered events are archived when the store supports it and no open transaction or uncertain tool intent remains. Manual compaction is not automatically archived.
 - `eventRetention: { maxEvents }` triggers compaction and archival when the active event count exceeds the threshold. It also requires an event store with `archive()` support.
 - Context overflow invokes the configured compactor, or the `onContextOverflow(messages, { abortSignal, reportUsage })` handler. Without either, generation throws `ContextOverflowError`. `maxContextOverflowRetries` defaults to `3`.
 - Open transactions and uncertain tool intents constrain when compaction and archival can proceed. Resolve them before manual compaction.

package/ts_agent/smartagent.events.ts

@@ -35,6 +35,8 @@ export interface IUserMessageEvent extends IAgentEventBase {
   type: 'user-message';
   content: TAgentUserMessage['content'];
   providerOptions?: TAgentUserMessage['providerOptions'];
+  /** Set when a running generation took the message in from its pending input. */
+  inputId?: string;
 }
 
 export interface IAssistantMessageEvent extends IAgentEventBase {
@@ -106,6 +108,11 @@ export interface IGenerationOutcomeEvent extends IAgentEventBase {
   generationId: string;
   outcome: TAgentGenerationOutcome;
   reason?: string;
+  /**
+   * Set on an `interrupted` outcome whose owner stopped the generation: what its model produced
+   * stays in the model context.
+   */
+  stopped?: boolean;
 }
 
 export interface IToolExecutionIntentEvent extends IAgentEventBase {
@@ -143,6 +150,8 @@ export type TAgentConversationEvent =
 
 export interface IContextCompactionEvent extends IAgentEventBase {
   type: 'context-compaction';
+  /** A proactive budget compaction whose settled source events may be archived automatically. */
+  automatic?: true;
   coveredEventIds: string[];
   replacementEvents: TAgentConversationEvent[];
   archivedTransactions?: IArchivedAgentGenerationTransaction[];