@modelprofile.com/flexharness 9.9.1 → 9.10.0

package/ts/readme.md

@@ -525,7 +525,7 @@ Attachment payloads are never copied into public audit messages or events. Publi
 }
 ```
 
-When the turn succeeds, the original string remains only in canonical private Agent events so a later model turn can receive the attachment again. Failed, cancelled, resolver-failed, cleanup-failed, and persistence-failed turns do not add it to future context.
+The original string remains only in canonical private Agent events, so a later model turn can receive the attachment again. A turn that succeeded stays in future context, and so does a turn stopped through `abort()` or `cancelPrompt()` once its model produced output: its prompt, the steers it took in and what the model produced before the stop, with every tool call that has no recorded result closed by an error result saying its effect is unknown. A turn stopped before any model output leaves no trace, so its prompt can be sent again without appearing twice; its `run.finished` event and finished queue entry carry `keptInContext: false`. Failed, resolver-failed, cleanup-failed, and persistence-failed turns, and turns a process restart interrupted, do not add anything to future context.
 
 The main session methods are:
 
@@ -572,6 +572,7 @@ await harness.cancelScheduledPrompt(scopeId, sessionId, scheduled.scheduleKey);
 await harness.getPromptQueueEntry(scopeId, sessionId, queued.queueId);
 await harness.listPromptQueueEntries(scopeId, sessionId);
 await harness.cancelPrompt(scopeId, sessionId, queued.queueId);
+await harness.steerPrompt(scopeId, sessionId, admission.queueId, { steerId, prompt });
 await harness.abort(scopeId, sessionId);
 await harness.listPendingPermissions(scopeId, sessionId);
 await harness.respondToPermission(scopeId, sessionId, permissionId, 'once');
@@ -616,6 +617,24 @@ 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.
 
+### Steering a Running Turn
+
+`steerPrompt()` hands a message to the running run of a prompt instead of queueing it behind that run:
+
+```typescript
+const admission = await harness.startPrompt(scopeId, sessionId, 'Plan the release.');
+await harness.steerPrompt(scopeId, sessionId, admission.queueId, {
+  steerId: 'steer-1',
+  prompt: 'Keep the database migration out of it.',
+});
+const result = await admission.completion;
+console.log(result.unappliedSteerIds); // [] once the run took the steer in
+```
+
+The run takes a steer in 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 a pending permission is never interrupted; the steer waits for the boundary that follows it. A steer taken in is a user message of the run (`steerId` set) that the model sees in its next call and every later turn. If the run had already answered, the assistant message that answered is completed and the run answers on in a new assistant message after the steer; a steer taken in before the run answered anything is placed before its still empty assistant message. `IFlexPromptResult.userMessage` stays the prompt and `assistantMessage` is the run's last assistant message. Undo and redo treat the run's messages as one turn.
+
+`steerPrompt()` resolves with `{ steerId, queueId, runId }` once the run accepted the steer and `prompt.steer.accepted` was emitted; `prompt.steer.applied` carries the `messageId` of the user message the steer became. Every accepted steer ends in exactly one of two ways: it is in the model context of later turns, or it is listed in `unappliedSteerIds`, in arrival order, on `IFlexPromptResult` and `run.finished`, and on the finished queue entry when that list is not empty. A steer is listed when the run did not take it in before it ended, because its last model step was already running or because it was stopped or failed, and also when the run itself does not stay in context. `keptInContext` on `run.finished` and on the finished queue entry says whether it does: it is `false` for a failed run and for a run stopped before any model output, and such a run lists every steer it accepted, including the ones it took in and reported with `prompt.steer.applied`. Send its prompt and its unapplied steers again to have them answered. The run stops taking steers atomically when its generation ends or `abort()`/`cancelPrompt()` stops it. A steer for a prompt without a running run, or whose run is ending, is refused with `FlexHarnessSteerRejectedError` reason `not-running`; the caller sends it as the next turn instead. Reusing a `steerId` within a run is refused with reason `duplicate`, an unknown `queueId` throws `FlexHarnessNotFoundError`, and subagent sessions are not steerable. A run holds at most `maxOutstandingPromptsPerSession` pending steers, and their bytes count against the session's outstanding prompt byte limit until the run takes them in or ends, so `startPrompt()` and `enqueuePrompt()` are refused with `FlexHarnessQueueFullError` while pending steers fill it. They are process-local like queue entries: a process restart ends the run and drops its pending steers, while steers it took in are durable parts of the turn.
+
 ## Slash Commands
 
 `parseSlashCommand()` is the public strict pure parser. It accepts at most 768 KiB, returns `not-command` for input not starting with `/`, `malformed` for invalid slash syntax, and `parsed` with the exact input, lowercase command name, separator-stripped raw argument text, and OpenCode-compatible quoted tokenization. Command names match `[a-z][a-z0-9-]{0,63}`. Single and double quotes group tokens and are stripped; escapes are not interpreted.
@@ -983,6 +1002,14 @@ const unsubscribe = harness.subscribe((event) => {
       break;
     case 'run.finished':
       markRunFinished(event.runId, event.status);
+      // A run that did not stay in context needs its prompt sent again, followed by its unapplied steers.
+      resendAsNextTurn(event.keptInContext ? [] : [event.runId], event.unappliedSteerIds);
+      break;
+    case 'prompt.steer.accepted':
+      markSteerPending(event.steerId);
+      break;
+    case 'prompt.steer.applied':
+      markSteerApplied(event.steerId, event.messageId);
       break;
     case 'session.history.changed':
       refreshSelectedSession(event.sessionId);
@@ -999,7 +1026,7 @@ const unsubscribe = harness.subscribe((event) => {
 unsubscribe();
 ```
 
-Events are discriminated, deeply immutable values with one global sequence within each `FlexHarness` instance. Every `IFlexEventBase` carries the exact source `sessionGenerationId` and `sessionGenerationSequence`; `session.deleted` retains the deleted generation after live metadata is removed. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part emits exactly one `part.completed` event before the corresponding `run.finished` event. Every `part.started`, `part.delta`, `part.updated`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences.
+Events are discriminated, deeply immutable values with one global sequence within each `FlexHarness` instance. Every `IFlexEventBase` carries the exact source `sessionGenerationId` and `sessionGenerationSequence`; `session.deleted` retains the deleted generation after live metadata is removed. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Every accepted steer emits `prompt.steer.accepted`, and `prompt.steer.applied`, after the `message.*` events of its user message, once the run took it in; `run.finished` lists it in `unappliedSteerIds` unless it is in the model context of later turns. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part emits exactly one `part.completed` event before the corresponding `run.finished` event. Every `part.started`, `part.delta`, `part.updated`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences.
 
 `part.started`, `part.updated`, and `part.completed` are snapshot events with a complete immutable `part`. A newly streamed text part emits `part.started` with empty text before its first delta; reasoning parts also start empty. `part.delta` is a separate delta-only event: it has no cumulative `part`, and carries `partType`, the required exact source `delta`, and `baseTextUtf8Bytes`/`textUtf8Bytes` for the cumulative text before and after that delta. The counters remain correct when a UTF-16 surrogate pair is split across callbacks. Exact deltas are never truncated, including a single delta above the 96 KiB message-transfer text limit. `part.updated` remains a cumulative replacement snapshot for running tool output or metadata, not a text delta. `session.history.changed` carries `direction: 'undo' | 'redo' | 'branch'`; `runId` is present for undo and redo. Events contain public IDs, exact delta payloads, and public snapshots only; they do not expose prompt payloads, the resolved scope object, storage key, model object, provider options, or raw storage key.
 

package/ts/utils.json.ts

@@ -720,6 +720,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       'usage',
       'error',
       'limit',
+      'steerId',
     ],
     path,
   );
@@ -736,6 +737,12 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
   requireOptionalString(message.completedAt, `${path}.completedAt`);
   requireOptionalString(message.error, `${path}.error`);
   requireOptionalModelLimit(message.limit, `${path}.limit`);
+  if (message.steerId !== undefined) {
+    requireString(message.steerId, `${path}.steerId`);
+    if (message.role !== 'user') {
+      throw new FlexHarnessStoreFormatError(`${path}.steerId is only valid on a user message.`);
+    }
+  }
   if (message.model !== undefined) validateModel(message.model, `${path}.model`);
   if (message.usage !== undefined) validateUsage(message.usage, `${path}.usage`);
   if (!Array.isArray(message.parts)) {

package/ts/utils.transfer.ts

@@ -172,6 +172,7 @@ export function createBoundedTransferMessage(message: IFlexMessage): IFlexMessag
   requireTransferIdentifier(projected.messageId, 'messageId');
   requireTransferIdentifier(projected.sessionId, 'sessionId');
   requireTransferIdentifier(projected.runId, 'runId');
+  if (projected.steerId !== undefined) requireTransferIdentifier(projected.steerId, 'steerId');
   projected.createdAt = truncateUtf8(projected.createdAt, 128);
   if (projected.completedAt !== undefined) projected.completedAt = truncateUtf8(projected.completedAt, 128);
   if (projected.error !== undefined) projected.error = truncateUtf8(projected.error, maxTransferMetadataBytes);