@modelprofile.com/flexharness 10.1.0 → 10.2.1

package/ts/interfaces.ts

@@ -513,6 +513,25 @@ export interface IFlexMessagePage {
   nextCursor?: string;
 }
 
+/**
+ * A session as the events up to `sequence` describe it, read in one step. Replaying the events of
+ * the same harness instance after `sequence` onto it gives the session's later states.
+ */
+export interface IFlexSessionView {
+  /** Current metadata. Its status can be ahead of `sequence`: status changes emit no event. */
+  session: IFlexSession;
+  /** The visible messages, including what a running turn has streamed so far. */
+  messages: IFlexMessage[];
+  /**
+   * The session's pending permission requests, oldest first. A request its run leaves unanswered,
+   * because the run was stopped or failed, leaves this list without an event of its own; the run's
+   * `run.finished` follows.
+   */
+  pendingPermissions: IFlexPermissionRequest[];
+  /** The `sequence` of the instance's last event this view includes; 0 before the first event. */
+  sequence: number;
+}
+
 export interface IFlexResolvedScope<TScope> {
   storageKey: string;
   scope: TScope;

package/ts/readme.md

@@ -789,14 +789,14 @@ for (const group of info.groups) {
 
 The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. It never includes capture IDs or provider references.
 
-`workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, the required canonical `sessionGenerationId` and `sessionGenerationSequence`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, deterministic per-segment `operationId`, and `direction`; release contexts contain the reference. Deleted-session recovery retains the same generation from the durable tombstone, so providers can reject callbacks from an older same-ID generation.
+`workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, the required canonical `sessionGenerationId` and `sessionGenerationSequence`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, per-segment `operationId`, and `direction`; release contexts contain the reference. Deleted-session recovery retains the same generation from the durable tombstone, so providers can reject callbacks from an older same-ID generation.
 
 The protocol is durable and inspectable:
 
 1. FlexHarness persists a `preparing` capture intent before calling `prepare()`, before model or tool execution. The provider must establish exclusive capture ownership for that `storageKey` and retain it until `release()` succeeds.
 2. `inspectCapture()` returns `missing`, `prepared`, `finalized`, or `unknown`. A finalized V1 result includes `reference`; a finalized V2 result includes the complete tagged `outcome`. `missing` is safe only while the durable state is still `preparing`; a missing prepared or finalizing capture, an `unknown` result, or an inspection failure fences the namespace.
 3. `finalize()` closes the capture and returns its JSON-safe V1 reference or complete V2 outcome. FlexHarness may call it during normal finalization or recovery after `inspectCapture()` reports `prepared`. Failed and cancelled root turns are captured too. A root capture spans its admitted subagent effects, including asynchronous children joined before finalization, although child transcript records remain separate. A failed parent cancels its outstanding children before joining them.
-4. Before undo or redo, FlexHarness persists an apply write-ahead record. `inspectApply()` must report the exact durable outcome for the supplied `operationId`: `not-applied` means no effect occurred, `applied` means the complete effect occurred, and `unknown` means the provider cannot prove either result. FlexHarness calls `apply()` only for `not-applied`; after an apply error it inspects again, and an `unknown` result or inspection failure fences the namespace. Progress is persisted after each segment, and the transcript cursor moves only after the complete unit succeeds. Known zero-progress failures leave the cursor unchanged and can be retried; partial progress retains the write-ahead record and resumes after restart. Caller cancellation is honored until the first workspace segment makes progress; recovery then continues with fresh bounded maintenance signals until the unit and cursor commit. Providers must treat `operationId` idempotently.
+4. Before undo or redo, FlexHarness persists an apply write-ahead record. `inspectApply()` must report the exact durable outcome for the supplied `operationId`: `not-applied` means no effect occurred, `applied` means the complete effect occurred, and `unknown` means the provider cannot prove either result. FlexHarness calls `apply()` only for `not-applied`; after an apply error it inspects again, and an `unknown` result or inspection failure fences the namespace. Progress is persisted after each segment, and the transcript cursor moves only after the complete unit succeeds. Known zero-progress failures leave the cursor unchanged and can be retried; partial progress retains the write-ahead record and resumes after restart. Caller cancellation is honored until the first workspace segment makes progress; recovery then continues with fresh bounded maintenance signals until the unit and cursor commit. Each `operationId` is unique to one apply of one segment: a later undo or redo gets a new ID even when it moves the same turn between the same cursors, such as undoing a turn again after a redo. Retries of that apply, in-process or after a restart, reuse its persisted ID, so providers must treat `operationId` idempotently and may record applied IDs to answer `inspectApply()`.
 5. `release()` relinquishes the capture after no-change or nonrevertible V2 finalization, branch commitment, retention or archive pruning, session deletion, or other durable removal. It must be idempotent: an unacknowledged release remains persisted and is retried before FlexHarness discards the reference.
 
 Under `workspace-required`, a group is a barrier when any segment is pending, nonrevertible, or legacy transcript-only history. It is a candidate when at least one segment is revertible and none is a barrier; otherwise it is no-change. Only candidates can be traversed. No-change groups after a candidate travel with that candidate until the next candidate or barrier. Leading no-change groups remain visible. A retained barrier blocks older groups, while later candidates remain undoable. A mixed revertible/nonrevertible group is a barrier.
@@ -1034,6 +1034,8 @@ 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`. 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.
 
+`getSessionView(scopeId, sessionId)` reads a session's metadata, visible messages and pending permission requests in one step, together with the instance's event `sequence` they include. The messages include what a running turn has streamed so far, so a consumer that applies every event of the instance with a greater `sequence` follows the session exactly from the view on; events up to `sequence` are already in it. The read waits while a queued write or a change that emits events for the session is in progress; a session that keeps changing through 64 consecutive waits is refused with `FlexHarnessSessionBusyError`, and the read can be repeated. Session metadata is current: status changes such as `waiting_permission` emit no event. A permission request its run leaves unanswered leaves `pendingPermissions` without an event of its own; the run's `run.finished` follows.
+
 `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.
 
 Part events narrow through the exported `TFlexPartEvent` union. `IFlexPartEventBase` contains their shared coordinates, `IFlexPartSnapshotEvent` owns snapshot events and their complete `part`, and `IFlexPartDeltaEvent` owns exact delta-only events and their UTF-8 counters.

package/ts_chat_harness/classes.transcript.ts

@@ -25,14 +25,23 @@ export interface IFlexHarnessTranscriptOptions {
   sessionId: string;
 }
 
-/** What `load()` reads: the session's authoritative state, as the harness APIs return it. */
+/**
+ * What `load()` reads: the session's authoritative state, as the harness APIs return it. Take it
+ * from `getSessionView()`, whose `sequence` ties the state to the event stream.
+ */
 export interface IFlexHarnessTranscriptSnapshot {
-  /** `getMessages()` of the session. */
+  /** `messages` of `getSessionView()`, or `getMessages()` of the session. */
   messages: readonly IFlexMessage[];
-  /** `listPendingPermissions()` of the session. */
+  /** `pendingPermissions` of `getSessionView()`, or `listPendingPermissions()` of the session. */
   permissions?: readonly IFlexPermissionRequest[];
-  /** `getSession()`; states whether a run is active or failed. */
+  /** `session` of `getSessionView()`, or `getSession()`; states whether a run is active or failed. */
   session?: IFlexSession;
+  /**
+   * `sequence` of `getSessionView()`: the last event of the instance the state includes. With it,
+   * the transcript skips the events the state already holds and proves that none after it was
+   * lost; without it, the first event after `load()` is taken unchecked.
+   */
+  sequence?: number;
   /** `getProjectState()`, when project management is enabled. */
   project?: IFlexProjectStateResult;
 }
@@ -120,6 +129,10 @@ export class FlexHarnessTranscript {
   private readonly timings = new Map<string, IFlexPartTiming>();
   private readonly partBytes = new Map<string, number>();
   private readonly permissionRows = new Map<string, plugins.IHarnessPermissionRequest>();
+  /** The run of every unanswered permission row; a run that finishes leaves them unanswerable. */
+  private readonly permissionRuns = new Map<string, string>();
+  /** The last event of the instance the transcript holds, once a view tied it to the stream. */
+  private followedSequence?: number;
   private status: plugins.IHarnessStatus = { type: 'idle' };
   private usage: plugins.IHarnessUsage = {};
   private todos: plugins.IHarnessTodoItem[] = [];
@@ -146,9 +159,9 @@ export class FlexHarnessTranscript {
     this.partBytes.clear();
     for (const message of snapshot.messages) this.upsertMessage(message);
     this.permissionRows.clear();
-    for (const request of snapshot.permissions ?? []) {
-      this.permissionRows.set(request.permissionId, flexPermissionToHarness(request));
-    }
+    this.permissionRuns.clear();
+    for (const request of snapshot.permissions ?? []) this.addPermission(request);
+    this.followedSequence = snapshot.sequence;
     this.status = snapshot.session ? flexSessionToHarnessStatus(snapshot.session) : { type: 'idle' };
     this.usage = this.flexMessages.reduce<plugins.IHarnessUsage>(
       (total, message) => message.usage ? sumUsage(total, flexUsageToHarness(message.usage)) : total,
@@ -179,15 +192,23 @@ export class FlexHarnessTranscript {
 
   /**
    * Takes one event of the harness instance. An event that does not directly follow
-   * `delivery.precedingSequence` means events were lost, possibly of this session, so the change
-   * asks for a reload.
+   * `delivery.precedingSequence`, or after a load with `sequence` the last event the transcript
+   * holds, means events were lost, possibly of this session, so the change asks for a reload. An
+   * event the loaded state already includes changes nothing.
    */
   public applyEvent(
     event: TFlexHarnessEvent,
     delivery: IFlexHarnessEventDelivery,
   ): IFlexHarnessTranscriptChange {
     const change = noChange();
-    if (
+    if (this.followedSequence !== undefined) {
+      if (event.sequence <= this.followedSequence) return change;
+      if (event.sequence !== this.followedSequence + 1) {
+        change.reload = true;
+        return change;
+      }
+      this.followedSequence = event.sequence;
+    } else if (
       delivery.precedingSequence !== undefined
       && event.sequence !== delivery.precedingSequence + 1
     ) {
@@ -202,7 +223,7 @@ export class FlexHarnessTranscript {
         this.setStatus(change, flexSessionToHarnessStatus(event.session));
         break;
       case 'session.deleted':
-        this.load({ messages: [] });
+        this.load({ messages: [], sequence: this.followedSequence });
         change.messages = change.permissions = change.status = change.usage = true;
         break;
       case 'run.started':
@@ -230,7 +251,7 @@ export class FlexHarnessTranscript {
         this.applyPartDelta(change, event);
         break;
       case 'permission.requested':
-        this.permissionRows.set(event.request.permissionId, flexPermissionToHarness(event.request));
+        this.addPermission(event.request);
         change.permissions = true;
         break;
       case 'permission.resolved': {
@@ -238,12 +259,20 @@ export class FlexHarnessTranscript {
         if (!row) break;
         row.response = event.decision;
         row.respondedAt = timestamp;
+        this.permissionRuns.delete(event.request.permissionId);
         change.permissions = true;
         break;
       }
       case 'run.finished':
         this.upsertMessage(event.message);
         change.messages = true;
+        // A request the run left unanswered can no longer be answered, and gets no event of its own.
+        for (const [permissionId, runId] of [...this.permissionRuns]) {
+          if (runId !== event.runId) continue;
+          this.permissionRows.delete(permissionId);
+          this.permissionRuns.delete(permissionId);
+          change.permissions = true;
+        }
         if (event.message.usage) {
           this.usage = sumUsage(this.usage, flexUsageToHarness(event.message.usage));
           change.usage = true;
@@ -268,6 +297,11 @@ export class FlexHarnessTranscript {
     return change;
   }
 
+  private addPermission(request: IFlexPermissionRequest): void {
+    this.permissionRows.set(request.permissionId, flexPermissionToHarness(request));
+    this.permissionRuns.set(request.permissionId, request.runId);
+  }
+
   private setStatus(change: IFlexHarnessTranscriptChange, status: plugins.IHarnessStatus): void {
     if (status.type === this.status.type && status.message === this.status.message) return;
     this.status = status;

package/ts_chat_harness/readme.md

@@ -35,15 +35,18 @@ function apply(event: TFlexHarnessEvent): void {
 
 async function reloadSession(): Promise<void> {
   buffered = [];
+  const view = await harness.getSessionView(scopeId, sessionId);
   transcript.load({
-    messages: await harness.getMessages(scopeId, sessionId),
-    permissions: await harness.listPendingPermissions(scopeId, sessionId),
-    session: await harness.getSession(scopeId, sessionId),
+    messages: view.messages,
+    permissions: view.pendingPermissions,
+    session: view.session,
+    sequence: view.sequence,
   });
   precedingSequence = undefined;
   Object.assign(chat, transcript.view());
   const pending = buffered;
   buffered = undefined;
+  // Buffered events the view already includes change nothing.
   for (const event of pending) {
     if (buffered) break; // a reported gap started another reload
     apply(event);
@@ -63,14 +66,14 @@ chat.addEventListener('harness-abort', () => send(flexHarnessAbortIntent(target)
 
 ## Transcript
 
-`FlexHarnessTranscript` follows one session. `load()` takes its authoritative state from `getMessages()`, `listPendingPermissions()`, `getSession()` and, with project management, `getProjectState()`. `applyEvent()` takes every harness event, ignores those of other sessions, and returns what changed.
+`FlexHarnessTranscript` follows one session. `load()` takes its authoritative state from `getSessionView()` and, with project management, `getProjectState()`. `applyEvent()` takes every harness event, ignores those of other sessions, and returns what changed.
 
-The host forwards every event of the harness instance, of every session, in order, and passes the `sequence` of the event it received before as `precedingSequence` (`undefined` for the first event after `load()`). Event sequences are global to the instance, so only this proves that no event of the session was lost: an event that does not directly follow its predecessor asks for a reload. After a gap or a reconnect, the host calls `load()` and starts again with `precedingSequence: undefined`. A snapshot cannot yet be tied to an event sequence: the session reads do not state which event they include, so the first event after `load()` is taken unchecked, and a buffered event the snapshot already holds can repeat it (a repeated text delta then fails its byte check and asks for another reload). `view()` returns a copy of the component inputs: `messages`, `permissions`, `questions`, `status`, `usage`, `todos` and `scratchpad`. The transcript keeps its own objects, so the deltas the components apply to theirs never apply twice.
+The host forwards every event of the harness instance, of every session, in order, and passes the `sequence` of the event it received before as `precedingSequence` (`undefined` for the first event after `load()`). Event sequences are global to the instance, so only this proves that no event of the session was lost: an event that does not directly follow its predecessor asks for a reload. After a gap or a reconnect, the host calls `load()` and starts again with `precedingSequence: undefined`. `getSessionView()` states the `sequence` of the last event its state includes; passed to `load()`, it lets the transcript skip the events the state already holds and prove that the first event after it follows. A snapshot from `getMessages()`, `listPendingPermissions()` and `getSession()` carries no sequence, so the first event after such a `load()` is taken unchecked. `view()` returns a copy of the component inputs: `messages`, `permissions`, `questions`, `status`, `usage`, `todos` and `scratchpad`. The transcript keeps its own objects, so the deltas the components apply to theirs never apply twice.
 
 - A user message is one row. An assistant message has one row per part, in part order: a text row, a reasoning row, or a tool row, so every streamed delta addresses exactly one row. The run's usage and error attach to its last text or reasoning row. Rows carry `order` from the message and part positions.
 - `change.deltas` stream text, reasoning, tool updates and part ends into the rows the components already hold. When `change.messages` is true, rows were added or replaced: assign `view().messages` instead.
 - `change.reload` means the transcript can no longer follow incrementally: events were lost, the history moved (`session.history.changed` after undo, redo or a branch), or a delta does not continue the text the transcript holds, which the delta's UTF-8 byte counters prove. Read the session again and call `load()`.
-- Permission rows stay in the transcript once answered, showing the decision.
+- Permission rows stay in the transcript once answered, showing the decision. A request its run leaves unanswered, because the run was stopped or failed, is removed when the run finishes.
 - FlexHarness emits no event for project state. After a run, or after a project tool's row completes, read `getProjectState()` and pass it to `applyProjectState()` for the task list and the scratchpad.
 - `questions` is always empty: FlexHarness has no question requests.
 - Messages the session has not taken in yet (a queued prompt, a steer) carry no text in FlexHarness events. The host that sent them shows them as pending rows.