@modelprofile.com/flexharness 9.9.1 → 9.10.0

package/ts/classes.flexharness.ts

@@ -13,6 +13,7 @@ import {
   FlexHarnessSessionBusyError,
   FlexHarnessSlashCommandReentryError,
   FlexHarnessSlashCommandUnavailableError,
+  FlexHarnessSteerRejectedError,
   FlexHarnessStoreConflictError,
   FlexHarnessStoreCommitUncertainError,
   FlexHarnessValidationError,
@@ -58,6 +59,8 @@ import type {
   IFlexPermissionRequestInput,
   IFlexPermissionSnapshot,
   IFlexProjectGoalResult,
+  IFlexSteerAdmission,
+  IFlexSteerInput,
   IFlexProjectManagementSessionContext,
   IFlexProjectManagementSnapshot,
   IFlexProjectManagementTombstone,
@@ -407,6 +410,31 @@ interface IActiveRun {
   delegatedRunAdmissionOwner?: IDelegatedRunAdmissionOwner;
   delegatedRunAdmissionClose?: Promise<void>;
   completion: Promise<IFlexPromptResult>;
+  steering: IRunSteering;
+  /** Stops the run's generation for its owner, so what the model produced stays in context. */
+  stop: AbortController;
+}
+
+/** The steers of a run: the input its generation takes in, and the prompts it accepted for it. */
+interface IRunSteering {
+  readonly input: plugins.AgentPendingInputQueue;
+  /** The session whose outstanding prompt bytes hold the bytes of the steers not taken in yet. */
+  readonly stored: IStoredSessionState;
+  /** Every steer the run accepted, in arrival order, by steer id. */
+  readonly accepted: Map<string, { prompt: INormalizedFlexPrompt; byteSize: number }>;
+  /** Accepted steers the generation recorded durably as user messages of the run. */
+  readonly applied: Set<string>;
+  /** Whether the run stays in the model context of later turns, once that is established. */
+  keptInContext?: boolean;
+  /** What became of the run's steers, fixed when the run ends. */
+  outcome?: IRunSteeringOutcome;
+}
+
+interface IRunSteeringOutcome {
+  /** Whether the run's prompt, the steers it took in and what its model produced stay in context. */
+  readonly keptInContext: boolean;
+  /** Accepted steers the model context of later turns does not hold, in arrival order. */
+  readonly unappliedSteerIds: readonly string[];
 }
 
 interface IDelegatedRunAdmissionSeed {
@@ -472,6 +500,8 @@ interface IQueuedPrompt {
   options?: IFlexPromptOptions;
   delegationSeed?: IDelegatedRunAdmissionSeed;
   byteSize: number;
+  /** The steering of the run the prompt started, once it started one. */
+  steering?: IRunSteering;
   completion: Promise<IFlexPromptResult>;
   resolveCompletion: (result: IFlexPromptResult) => void;
   rejectCompletion: (error: unknown) => void;
@@ -2860,6 +2890,89 @@ export class FlexHarness<TScope = unknown> {
     );
   }
 
+  /**
+   * Steers the running run of the prompt `queueId`: the run takes `steer.prompt` in as a user
+   * message at its next step boundary, after the tool results of its current model step are
+   * recorded and before its next model call. A running tool call or permission wait is not
+   * interrupted. A steer the run has not taken in when it ends is reported in its
+   * `unappliedSteerIds`; a steer for a prompt that has no running run, or whose run is ending,
+   * is refused with `FlexHarnessSteerRejectedError` reason `not-running` and belongs to the
+   * next turn.
+   */
+  public async steerPrompt(
+    scopeId: string,
+    sessionId: string,
+    queueId: string,
+    steer: IFlexSteerInput,
+  ): Promise<IFlexSteerAdmission> {
+    validateIdentifier(queueId, 'queueId');
+    requireTransferIdentifier(queueId, 'queueId');
+    validateIdentifier(steer.steerId, 'steerId');
+    requireTransferIdentifier(steer.steerId, 'steerId');
+    this.assertOpen();
+    const prompt = normalizeFlexPrompt(steer.prompt);
+    const byteSize = this.promptAdmissionByteSize(steer.prompt, {});
+    const { state } = await this.resolveState(scopeId);
+    this.assertStateAcceptingWork(state);
+    const stored = this.requireSession(state, sessionId);
+    this.assertSessionWritable(stored);
+    if (stored.session.agent !== undefined) {
+      throw new FlexHarnessValidationError(
+        'Subagent sessions can only be prompted through the foreground delegate tool.',
+      );
+    }
+    const run = state.activeRuns.get(sessionId);
+    if (!run || run.queueId !== queueId) {
+      if (stored.outstandingPromptsById.has(queueId) || stored.terminalPromptQueueEntries.has(queueId)) {
+        throw new FlexHarnessSteerRejectedError('not-running', steer.steerId);
+      }
+      throw new FlexHarnessNotFoundError('Prompt queue entry', queueId);
+    }
+    const steering = run.steering;
+    if (!steering.input.closed && !steering.accepted.has(steer.steerId)) {
+      if (
+        steering.accepted.size - steering.applied.size
+        >= this.promptQueueLimits.maxOutstandingPromptsPerSession
+      ) {
+        throw new FlexHarnessQueueFullError(`Session "${sessionId}" has reached its pending steer limit.`);
+      }
+      // Pending steers hold outstanding prompt bytes of the session until they are taken in.
+      if (
+        steering.stored.outstandingPromptBytes + byteSize
+        > this.promptQueueLimits.maxOutstandingBytesPerSession
+      ) {
+        throw new FlexHarnessQueueFullError(
+          `Session "${sessionId}" has reached its outstanding prompt byte limit.`,
+        );
+      }
+    }
+    try {
+      steering.input.add({
+        inputId: steer.steerId,
+        content: cloneSerializable(prompt.modelMessage.content) as Parameters<
+          plugins.IAgentSession['beginGeneration']
+        >[0],
+      });
+    } catch (error) {
+      if (error instanceof plugins.AgentPendingInputRejectedError) {
+        throw new FlexHarnessSteerRejectedError(
+          error.reason === 'duplicate' ? 'duplicate' : 'not-running',
+          steer.steerId,
+        );
+      }
+      throw error;
+    }
+    steering.accepted.set(steer.steerId, { prompt, byteSize });
+    steering.stored.outstandingPromptBytes += byteSize;
+    this.emitEvent(run.scopeId, run.stored.session, {
+      type: 'prompt.steer.accepted',
+      queueId,
+      runId: run.runId,
+      steerId: steer.steerId,
+    });
+    return { steerId: steer.steerId, queueId, runId: run.runId };
+  }
+
   public async abort(scopeId: string, sessionId: string): Promise<boolean> {
     const { scope, state } = await this.resolveState(scopeId);
     const run = state.activeRuns.get(sessionId);
@@ -3966,7 +4079,16 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private createActiveRun(queued: IQueuedPrompt): IActiveRun {
+    const steering: IRunSteering = {
+      input: new plugins.AgentPendingInputQueue(),
+      stored: queued.stored,
+      accepted: new Map(),
+      applied: new Set(),
+    };
+    queued.steering = steering;
     return {
+      steering,
+      stop: new AbortController(),
       subagents: this.subagents,
       state: queued.state,
       stored: queued.stored,
@@ -4410,8 +4532,11 @@ export class FlexHarness<TScope = unknown> {
     const generateOptions = {
       transaction: run.transaction,
       abort: run.controller.signal,
+      stop: run.stop.signal,
       prepare: (context: { generationId: string; abortSignal: AbortSignal }) =>
         this.prepareGeneration(run, options, context.abortSignal),
+      pendingInput: run.steering.input,
+      onInputApplied: (input: plugins.IAgentAppliedInput) => this.applyRunSteer(run, input),
     };
     const generation = this.withRunCompactorContext(run, () => run.scheduleKey
       ? run.stored.agentSession.scheduleGenerate({
@@ -4482,11 +4607,16 @@ export class FlexHarness<TScope = unknown> {
     delete queued.prompt;
     delete queued.options;
     delete queued.delegationSeed;
+    const steering = queued.steering === undefined ? undefined : this.closeRunSteering(queued.steering);
     const terminal: IFlexPromptQueueEntry = {
       ...this.projectPromptQueueEntry(queued),
       status,
       finishedAt: new Date().toISOString(),
       ...(error === undefined ? {} : { error: errorToInfo(error) }),
+      keptInContext: steering?.keptInContext ?? false,
+      ...(steering === undefined || steering.unappliedSteerIds.length === 0
+        ? {}
+        : { unappliedSteerIds: [...steering.unappliedSteerIds] }),
     };
     stored.terminalPromptQueueEntries.set(queued.queueId, terminal);
     while (
@@ -4590,6 +4720,7 @@ export class FlexHarness<TScope = unknown> {
         await this.fenceNamespace(run.state, run, projected);
         throw projected;
       }
+      run.steering.keptInContext = true;
       run.phase = 'promoting';
       try {
         await this.promoteCompletedTerminal(run, terminal);
@@ -4616,6 +4747,7 @@ export class FlexHarness<TScope = unknown> {
         usage: publicSnapshot(terminal.usage!),
         finishReason: terminal.finishReason!,
         steps: terminal.steps!,
+        unappliedSteerIds: [...this.closeRunSteering(run.steering).unappliedSteerIds],
       };
     } catch (error) {
       if (run.state.lifecycle === 'fenced') {
@@ -4680,14 +4812,21 @@ export class FlexHarness<TScope = unknown> {
     try {
       await this.withRunCompactorContext(
         run,
-        () => run.stored.agentSession.finalizeGeneration(run.transaction!, desiredOutcome),
+        () => run.stored.agentSession.finalizeGeneration(
+          run.transaction!,
+          desiredOutcome,
+          { stopped: desiredOutcome === 'interrupted' && cancelled },
+        ),
       );
     } catch (finalizationError) {
       errors.push(this.projectExternalError(run, finalizationError, 'agentSession'));
     }
     let outcome: TCanonicalOutcome | undefined;
     try {
-      outcome = (await this.durableCanonicalOutcomes(run.stored)).get(run.runId);
+      const snapshot = await run.stored.eventStore.load(run.stored.session.sessionId);
+      const events = snapshot?.events ?? [];
+      outcome = this.canonicalOutcomes(events).get(run.runId);
+      run.steering.keptInContext = plugins.isGenerationInModelContext(events, run.runId);
     } catch (outcomeError) {
       errors.push(this.projectExternalError(run, outcomeError, 'persistence'));
     }
@@ -6238,17 +6377,7 @@ export class FlexHarness<TScope = unknown> {
       role: 'user',
       status: 'streaming',
       createdAt: timestamp,
-      parts: prompt.parts.map((part) => {
-        if (part.type === 'text') {
-          return { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: part.text };
-        }
-        return {
-          partId: plugins.crypto.randomUUID(),
-          type: 'attachment' as const,
-          attachmentType: part.type,
-          ...describeAttachment(part),
-        };
-      }),
+      parts: this.userMessageParts(prompt),
     };
     const assistantMessage: IFlexMessage = {
       messageId: run.assistantMessageId,
@@ -6262,6 +6391,151 @@ export class FlexHarness<TScope = unknown> {
     return { userMessage, assistantMessage };
   }
 
+  private userMessageParts(prompt: INormalizedFlexPrompt): TFlexMessagePart[] {
+    return prompt.parts.map((part) => {
+      if (part.type === 'text') {
+        return { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: part.text };
+      }
+      return {
+        partId: plugins.crypto.randomUUID(),
+        type: 'attachment' as const,
+        attachmentType: part.type,
+        ...describeAttachment(part),
+      };
+    });
+  }
+
+  /**
+   * Ends steering intake once the run's generation has settled and fixes what became of its
+   * steers. A run that stays in the model context reports the steers its generation did not
+   * record; a run that does not, because it failed, was stopped before any model output or its
+   * outcome could not be established, reports every steer it accepted, since the model context
+   * of later turns holds none of them. The bytes of the steers not taken in are released.
+   */
+  private closeRunSteering(steering: IRunSteering): IRunSteeringOutcome {
+    if (steering.outcome) return steering.outcome;
+    steering.input.close();
+    const keptInContext = steering.keptInContext === true;
+    const unappliedSteerIds: string[] = [];
+    let heldBytes = 0;
+    for (const [steerId, entry] of steering.accepted) {
+      const applied = steering.applied.has(steerId);
+      if (!applied) heldBytes += entry.byteSize;
+      if (!keptInContext || !applied) unappliedSteerIds.push(steerId);
+    }
+    steering.stored.outstandingPromptBytes = Math.max(0, steering.stored.outstandingPromptBytes - heldBytes);
+    steering.outcome = Object.freeze({
+      keptInContext,
+      unappliedSteerIds: Object.freeze(unappliedSteerIds),
+    });
+    return steering.outcome;
+  }
+
+  /**
+   * Projects a steer the run's generation took in as a user message of the run. The assistant
+   * message that answered before it is completed and the run answers on in a new one; a steer
+   * taken in before the run answered anything is placed before its still empty assistant message.
+   */
+  private async applyRunSteer(run: IActiveRun, applied: plugins.IAgentAppliedInput): Promise<void> {
+    const steering = run.steering;
+    const accepted = steering.accepted.get(applied.inputId);
+    if (
+      !accepted
+      || applied.generationId !== run.runId
+      || steering.applied.has(applied.inputId)
+      || steering.outcome !== undefined
+    ) {
+      throw new Error(`Steer "${applied.inputId}" was taken in without being accepted by its run.`);
+    }
+    // The generation recorded the steer durably: it is in the model context whenever the run is.
+    steering.applied.add(applied.inputId);
+    steering.stored.outstandingPromptBytes = Math.max(
+      0,
+      steering.stored.outstandingPromptBytes - accepted.byteSize,
+    );
+    const timestamp = new Date().toISOString();
+    const steerMessage: IFlexMessage = {
+      messageId: plugins.crypto.randomUUID(),
+      sessionId: run.sessionId,
+      runId: run.runId,
+      role: 'user',
+      status: 'completed',
+      createdAt: timestamp,
+      completedAt: timestamp,
+      steerId: applied.inputId,
+      parts: this.userMessageParts(accepted.prompt),
+    };
+    const answered = run.callbackParts.length > 0;
+    const answeredAssistantId = run.assistantMessageId;
+    let completedAssistant: IFlexMessage | undefined;
+    const nextAssistant: IFlexMessage | undefined = answered
+      ? {
+          messageId: plugins.crypto.randomUUID(),
+          sessionId: run.sessionId,
+          runId: run.runId,
+          role: 'assistant',
+          status: 'streaming',
+          createdAt: timestamp,
+          parts: [],
+        }
+      : undefined;
+    await this.mutateProjection(run.state, run.stored, () => {
+      const index = run.stored.messages.findIndex((message) => message.messageId === answeredAssistantId);
+      if (index < 0) throw new Error('The steered run has no projected assistant message.');
+      if (!nextAssistant) {
+        run.stored.messages.splice(index, 0, cloneSerializable(steerMessage));
+        return;
+      }
+      completedAssistant = {
+        ...cloneSerializable(run.stored.messages[index]),
+        status: 'completed',
+        completedAt: timestamp,
+        parts: cloneSerializable(run.callbackParts),
+        ...(run.modelResolution ? { model: cloneSerializable(run.modelResolution.identity) } : {}),
+      };
+      run.stored.messages.splice(
+        index,
+        1,
+        cloneSerializable(completedAssistant),
+        cloneSerializable(steerMessage),
+        cloneSerializable(nextAssistant),
+      );
+    });
+    if (completedAssistant && nextAssistant) {
+      run.assistantMessageId = nextAssistant.messageId;
+      run.reservedAssistantMessage = publicSnapshot(nextAssistant);
+      run.callbackParts = [];
+      run.reasoningPartIds.clear();
+      this.emitEvent(run.scopeId, run.stored.session, {
+        type: 'message.updated',
+        runId: run.runId,
+        messageId: completedAssistant.messageId,
+        message: publicSnapshot(completedAssistant),
+      });
+    }
+    this.emitEvent(run.scopeId, run.stored.session, {
+      type: 'message.created',
+      runId: run.runId,
+      messageId: steerMessage.messageId,
+      message: publicSnapshot(steerMessage),
+    });
+    if (nextAssistant) {
+      this.emitEvent(run.scopeId, run.stored.session, {
+        type: 'message.created',
+        runId: run.runId,
+        messageId: nextAssistant.messageId,
+        message: publicSnapshot(nextAssistant),
+      });
+    }
+    this.emitEvent(run.scopeId, run.stored.session, {
+      type: 'prompt.steer.applied',
+      queueId: run.queueId,
+      runId: run.runId,
+      steerId: applied.inputId,
+      messageId: steerMessage.messageId,
+    });
+  }
+
   private buildTerminal(
     run: IActiveRun,
     status: 'completed' | 'failed' | 'cancelled',
@@ -7428,16 +7702,45 @@ export class FlexHarness<TScope = unknown> {
     stored.stagedTerminals.push(cloneSerializable(terminal));
   }
 
+  /**
+   * Puts a run's terminal messages in place of their projected versions: its prompt, and its last
+   * assistant message. The steers a run took in, and the assistant messages it completed before
+   * them, stay where they are. A terminal message that is not projected yet is added: the prompt
+   * before the run's other messages, the assistant message after them.
+   */
   private replaceVisibleRun(stored: IStoredSessionState, terminal: IFlexTerminalProjection): void {
+    const replacements = new Map([
+      [terminal.userMessage.messageId, terminal.userMessage],
+      [terminal.assistantMessage.messageId, terminal.assistantMessage],
+    ]);
+    const placed = new Set<string>();
+    stored.messages = stored.messages.map((message) => {
+      const replacement = message.runId === terminal.runId
+        ? replacements.get(message.messageId)
+        : undefined;
+      if (!replacement) return message;
+      placed.add(replacement.messageId);
+      return cloneSerializable(replacement);
+    });
     const firstIndex = stored.messages.findIndex((message) => message.runId === terminal.runId);
-    stored.messages = stored.messages.filter((message) => message.runId !== terminal.runId);
-    const insertion = firstIndex < 0 ? stored.messages.length : firstIndex;
-    stored.messages.splice(
-      insertion,
-      0,
-      cloneSerializable(terminal.userMessage),
-      cloneSerializable(terminal.assistantMessage),
-    );
+    if (!placed.has(terminal.userMessage.messageId)) {
+      stored.messages.splice(
+        firstIndex < 0 ? stored.messages.length : firstIndex,
+        0,
+        cloneSerializable(terminal.userMessage),
+      );
+    }
+    if (!placed.has(terminal.assistantMessage.messageId)) {
+      const lastIndex = stored.messages.reduce(
+        (last, message, index) => message.runId === terminal.runId ? index : last,
+        -1,
+      );
+      stored.messages.splice(
+        lastIndex < 0 ? stored.messages.length : lastIndex + 1,
+        0,
+        cloneSerializable(terminal.assistantMessage),
+      );
+    }
   }
 
   private emitTerminalProjection(run: IActiveRun, terminal: IFlexTerminalProjection): void {
@@ -7473,6 +7776,7 @@ export class FlexHarness<TScope = unknown> {
     const status: IFlexRunFinishedEvent['status'] = error
       ? cancelled ? 'cancelled' : 'failed'
       : 'completed';
+    const steering = this.closeRunSteering(run.steering);
     this.emitEvent(run.scopeId, run.stored.session, {
       type: 'run.finished',
       runId: run.runId,
@@ -7480,6 +7784,8 @@ export class FlexHarness<TScope = unknown> {
       status,
       message: publicSnapshot(message),
       ...(error === undefined ? {} : { error: errorToInfo(error) }),
+      keptInContext: steering.keptInContext,
+      unappliedSteerIds: [...steering.unappliedSteerIds],
     });
   }
 
@@ -8156,6 +8462,8 @@ export class FlexHarness<TScope = unknown> {
     context?: IFlexAgentContextInvocation<TScope>,
   ): void {
     const invocationContext = context ?? this.createRunCompactorContext(run);
+    // A stopped run takes no further steers; the ones it has not taken in are reported unapplied.
+    run.steering.input.close();
     if (run.internalFailure === undefined && run.ownerCancellation === undefined) {
       run.ownerCancellation = reason;
       run.deferredCompactorContext = invocationContext;
@@ -8165,6 +8473,8 @@ export class FlexHarness<TScope = unknown> {
       (run.deferredCompactorContext ?? invocationContext) as IFlexAgentContextInvocation<TScope>,
       () => {
         this.rejectRunPermissions(run.state, run, reason);
+        // The owner stops the generation: what its model produced stays in the model context.
+        if (run.ownerCancellation === reason && !run.stop.signal.aborted) run.stop.abort(reason);
         if (!run.controller.signal.aborted) run.controller.abort(reason);
         if (run.phase === 'admitting') return;
         if (run.scheduleKey) {
@@ -8182,6 +8492,7 @@ export class FlexHarness<TScope = unknown> {
     context?: IFlexAgentContextInvocation<TScope>,
   ): void {
     const invocationContext = context ?? this.createRunCompactorContext(run);
+    run.steering.input.close();
     if (run.internalFailure === undefined) {
       run.internalFailure = error ?? new Error('Internal FlexHarness run failure.');
       run.deferredCompactorContext = invocationContext;
@@ -9265,8 +9576,12 @@ export class FlexHarness<TScope = unknown> {
     status: 'completed' | 'failed' | 'cancelled',
   ): IFlexTerminalProjection {
     const timestamp = new Date().toISOString();
-    const sourceUser = stage?.userMessage ?? visible.find((message) => message.role === 'user');
-    const sourceAssistant = stage?.assistantMessage ?? visible.find((message) => message.role === 'assistant');
+    // A steered run projects its prompt first and its steers after it; its last assistant
+    // message is the one that was still answering.
+    const sourceUser = stage?.userMessage
+      ?? visible.find((message) => message.role === 'user' && message.steerId === undefined);
+    const sourceAssistant = stage?.assistantMessage
+      ?? [...visible].reverse().find((message) => message.role === 'assistant');
     const userMessage: IFlexMessage = cloneSerializable(sourceUser ?? {
       messageId: plugins.crypto.randomUUID(),
       sessionId,

package/ts/errors.ts

@@ -44,6 +44,30 @@ export class FlexHarnessSessionBusyError extends FlexHarnessError {
   }
 }
 
+export type TFlexSteerRejection = 'not-running' | 'duplicate';
+
+/**
+ * The run refused a steer. `not-running`: the prompt has no run that takes input, because it
+ * has not started or its run is ending; the steer belongs to the next turn. `duplicate`: the run
+ * already accepted a steer with this id.
+ */
+export class FlexHarnessSteerRejectedError extends FlexHarnessError {
+  public readonly reason: TFlexSteerRejection;
+  public readonly steerId: string;
+
+  constructor(reason: TFlexSteerRejection, steerId: string) {
+    super(
+      reason === 'duplicate' ? 'FLEX_STEER_DUPLICATE' : 'FLEX_STEER_NOT_RUNNING',
+      reason === 'duplicate'
+        ? `Steer "${steerId}" was already accepted.`
+        : `Steer "${steerId}" has no running turn to join.`,
+    );
+    this.name = 'FlexHarnessSteerRejectedError';
+    this.reason = reason;
+    this.steerId = steerId;
+  }
+}
+
 /** 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/interfaces.ts

@@ -141,6 +141,8 @@ export interface IFlexMessage {
   error?: string;
   /** The model limit that failed this run, next to its error. */
   limit?: TFlexModelLimit;
+  /** On a user message that steered its running run: the caller's steer identity. */
+  steerId?: string;
 }
 
 export interface IFlexSessionActivity {
@@ -436,17 +438,46 @@ export interface IFlexPromptQueueEntry {
   startedAt?: string;
   finishedAt?: string;
   error?: IFlexErrorInfo;
+  /**
+   * 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.
+   */
+  keptInContext?: boolean;
+  /**
+   * On a finished entry whose run left steers unapplied: the steers it accepted that the model
+   * context of later turns does not hold, in the order they arrived. The caller decides what
+   * becomes of them.
+   */
+  unappliedSteerIds?: string[];
 }
 
 export interface IFlexPromptResult {
   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;
   usage: IFlexUsage;
   finishReason: string;
   steps: number;
+  /** Steers the run accepted but never took in, in the order they arrived. */
+  unappliedSteerIds: string[];
+}
+
+/** 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. */
+  steerId: string;
+  prompt: TFlexPrompt;
+}
+
+export interface IFlexSteerAdmission {
+  steerId: string;
+  queueId: string;
+  runId: string;
 }
 
 export interface IFlexPromptQueueAdmission {
@@ -1455,6 +1486,36 @@ export interface IFlexRunFinishedEvent extends IFlexEventBase {
   readonly status: 'completed' | 'failed' | 'cancelled';
   readonly message: IFlexMessage;
   readonly error?: IFlexErrorInfo;
+  /**
+   * Whether the run's prompt, the steers it 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 and a run stopped before any model output, whose
+   * prompt the caller sends again to have it answered.
+   */
+  readonly keptInContext: boolean;
+  /**
+   * Steers the run accepted that the model context of later turns does not hold, in the order
+   * they arrived: the ones it never took in, and, when the run is not kept in context, every
+   * steer it accepted.
+   */
+  readonly unappliedSteerIds: readonly string[];
+}
+
+/** The running run accepted a steer; it is taken in at the run's next step boundary. */
+export interface IFlexSteerAcceptedEvent extends IFlexEventBase {
+  readonly type: 'prompt.steer.accepted';
+  readonly queueId: string;
+  readonly runId: string;
+  readonly steerId: string;
+}
+
+/** The run took a steer in as the user message `messageId`, before its next model call. */
+export interface IFlexSteerAppliedEvent extends IFlexEventBase {
+  readonly type: 'prompt.steer.applied';
+  readonly queueId: string;
+  readonly runId: string;
+  readonly steerId: string;
+  readonly messageId: string;
 }
 
 /** The run waits `delayMs` before retrying a rate-limited or unavailable model call. */
@@ -1513,6 +1574,8 @@ export type TFlexHarnessEvent =
   | IFlexRunRetryingEvent
   | TFlexModelUsageEvent
   | IFlexPromptQueueEvent
+  | IFlexSteerAcceptedEvent
+  | IFlexSteerAppliedEvent
   | IFlexSessionHistoryChangedEvent;
 
 export type TFlexHarnessEventListener = (event: TFlexHarnessEvent) => void;

package/ts/plugins.ts

@@ -9,12 +9,15 @@ export { AsyncLocalStorage, crypto, fs, path };
 // @push.rocks scope
 import {
   AgentEventStoreConflictError,
+  AgentPendingInputQueue,
+  AgentPendingInputRejectedError,
   AgentSession,
   buildModelMessages,
   ToolJobStoreConflictError,
   createAgentEvent,
   filterModelVisibleAgentEvents,
   getAgentGenerationTransactions,
+  isGenerationInModelContext,
   modelMessagesToAgentEvents,
   tool,
   validateAgentEventArchiveV2,
@@ -24,12 +27,15 @@ import {
 
 export {
   AgentEventStoreConflictError,
+  AgentPendingInputQueue,
+  AgentPendingInputRejectedError,
   AgentSession,
   buildModelMessages,
   ToolJobStoreConflictError,
   createAgentEvent,
   filterModelVisibleAgentEvents,
   getAgentGenerationTransactions,
+  isGenerationInModelContext,
   modelMessagesToAgentEvents,
   tool,
   validateAgentEventArchiveV2,
@@ -37,6 +43,7 @@ export {
   z,
 };
 export type {
+  IAgentAppliedInput,
   IAgentEventArchiveV2,
   IAgentContextCompactionOptions,
   IAgentEventSnapshotV2,