@modelprofile.com/flexharness 9.10.0 → 10.1.0

package/ts/readme.md

@@ -61,10 +61,12 @@ or provider SDKs.
 | `/chat` | Portable streaming `ChatSession`, history and usage | None |
 | `/chat/cli` | Ink/React terminal chat | `ink ink-text-input react`; TypeScript: `@types/react` |
 | `/chat/web` | Lit `flexchat-window`, `flexchat-message`, `flexchat-input` | `lit` |
+| `/chat/harness` | `FlexHarnessTranscript` and intents for the `@design.estate/dees-catalog` harness components, browser-safe | `@design.estate/dees-catalog` (types only) |
 | `/kvm` | Browser control, terminal framing and OCR observation | `puppeteer` |
 | `/documents` | PDF and image documents, `extractTextFromPdf` | `@push.rocks/smartpdf`; for image documents `sharp` |
 | `/mcp` | MCP clients and AI SDK tool conversion | `@modelcontextprotocol/sdk` |
 | `/migration` | Existing versioned harness migrations | None |
+| `/stores/nosqldb` | `NoSqlFlexHarnessStores`: cross-process CAS stores on `@lossless.org/client/nosqldb` | `@lossless.org/client` |
 
 The integrations in the last column use optional peer dependencies. Install them
 only for the entrypoints your project imports, for example:
@@ -403,26 +405,29 @@ Normal Flex session cleanup always waits in-flight local project operations, the
 
 `InMemoryFlexProjectManagementStore` is the standalone in-memory implementation. `InMemoryFlexHarnessStores` and `JsonFileFlexHarnessStores` include `projectManagement` as a required bundle member. `assertFlexProjectManagementSnapshot()` validates live records, `assertFlexProjectManagementTombstone()` validates tombstones, and `assertFlexProjectManagementRecord()` validates the union. `createEmptyFlexProjectManagementSnapshot(sessionGenerationId, sessionGenerationSequence)` returns a revision-0 live state for the supplied current generation.
 
-## Foreground Subagents
+## Subagents
 
-`subagents` enables a harness-owned built-in tool named `delegate`. It is available only when at least one definition exists and the current session depth is below `maxSubagentDepth`. An application or resource `toolProvider` must not return its own `delegate` tool while the built-in is enabled for that run. The built-in is foreground-only: the parent tool call does not complete until the child prompt reaches a terminal outcome.
+`subagents` enables the harness-owned `delegate` and `delegate_result` tools when at least one definition exists and the session depth is below `maxSubagentDepth`. A tool provider cannot replace either enabled built-in. Delegation is asynchronous by default: `delegate` returns `{ taskId, status: 'running', runId }` after durable child admission, so the parent can continue independent work. `delegate_result({ taskId, waitMs? })` reads live status and, once settled, bounded final text and model identity; its optional wait is limited to 240 seconds and observes parent cancellation. Set `foreground: true` to await the final answer in `delegate` itself. Children remain owned by the parent turn: Stop cancels its exact child runs, and the parent joins them before releasing authority and finalizing. A child result arriving while inference is still active enters the parent's next model context as untrusted task data.
 
 The model calls it with this exact input shape:
 
+When upgrading from 9.x, callers that require the previous synchronous delegate result must pass `foreground: true`. Tool providers must also leave the newly reserved `delegate_result` name available when subagents are enabled.
+
 ```typescript
 interface IDelegateInput {
   description: string;
   prompt: string;
   subagentType: string;
   taskId?: string;
+  foreground?: boolean;
 }
 ```
 
 Before creating or resuming a child, FlexHarness requests permission on the parent run with `kind: 'subagent.start'`, the parent `toolCallId`, and separately bounded harness-owned agent/task metadata. Its metadata includes `childSessionId`, the exact ID reserved for this call: FlexHarness derives it deterministically when `taskId` is omitted and copies the supplied candidate when `taskId` is present. A resume also retains that candidate as `taskId`. This block is not truncated by `toolOutputLimits`. The reserved ID binds permission handling before child creation but does not prove that the child exists or is owned: applications must treat the later delegated admission context as authoritative. The controller answers through the normal permission APIs. This request has no `rememberKey`, so `always` is invalid; controllers use `once` or `reject`.
 
-Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` remains limited to `sessionId`, `sessionGenerationId`, and `title`. Child sessions reject direct `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the foreground `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
+Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` remains limited to `sessionId`, `sessionGenerationId`, and `title`. Child sessions reject direct `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
 
-The parent tool part receives `childSessionId` in a cumulative `part.updated` event as soon as the child is acquired. If child model resolution completes, a later cumulative update adds `model`; failures before model resolution leave it absent. The terminal tool part retains every value that became available. A successful delegate call always has model identity and returns bounded JSON:
+The parent tool part receives `childSessionId` as soon as the child is acquired, so a host can offer an authorized live transcript. A foreground call also adds the resolved child model to its part and returns bounded JSON:
 
 ```typescript
 {
@@ -687,7 +692,7 @@ At most 128 custom commands may be registered. Every registration must be a plai
 
 `/undo` and `/redo`, plus `undoSession()` and `redoSession()`, move a durable history cursor. The direct methods return `{ revertedRunId }` and `{ restoredRunId }`; the slash forms return `{ type: 'operation', name: 'undo' | 'redo' }`. Each committed cursor move emits one `session.history.changed` event with `direction`, `runId`, and the selected session identity. A committed branch emits the same event with `direction: 'branch'` and no `runId`, so controllers should refresh the complete selected session. Capture finalization, cleanup, and metadata-only changes do not emit this event.
 
-A completed root-session turn defines an operation-group boundary. Failed and cancelled turns after it belong to that group; leading failed or cancelled turns belong to the first completed group. No completed boundary means there is nothing to undo. Undo applies selected segments in reverse order and redo applies them in forward order. Without `turnReversionProvider`, only transcript and future model context move. Hidden messages disappear from `getMessages()`, message pages, exact message lookup, and future model context. Starting a new prompt, template, handler, or compaction from an undone position commits a branch: hidden messages and segments are removed durably and cannot be redone. Successful event archival also commits hidden redo history; a missing compaction or failed archive leaves it intact.
+A completed root-session turn defines an operation-group boundary. Failed and cancelled turns after it belong to that group; leading failed or cancelled turns belong to the first completed group. No completed boundary means there is nothing to undo. Undo applies selected segments in reverse order and redo applies them in forward order. Without `turnReversionProvider`, only transcript and future model context move. Hidden messages disappear from `getMessages()`, message pages, exact message lookup, and future model context. Starting a new prompt, template, handler, or compaction from an undone position commits a branch: hidden messages and segments are removed durably and cannot be redone. Successful event archival also commits hidden redo history; a missing compaction or failed archive leaves it intact. Automatic budget compaction archives covered events after generation finalization and advances the same undo horizon; set `contextCompactionBytes: false` to disable that automatic policy.
 
 Two horizons bound undo. Retention pruning removes the oldest complete visible units when `reversionLimits` is exceeded. Explicit event archival marks covered turns context-unavailable and prunes complete prefixes that can no longer be rebuilt; FlexHarness never crosses that archive horizon. Manual compaction without archival retains the original events and remains undoable. Schema-1 projection history and sessions migrated from `2.x` have no reversion segments, so historical turns are not retroactively undoable; newly written turns are tracked normally.
 
@@ -790,7 +795,7 @@ 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 foreground subagent effects, although child transcript records remain separate.
+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.
 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.
 
@@ -960,6 +965,7 @@ A `contextCompactor` states which model to compact with from the model the compa
 | `reason` | Compaction | Model members |
 | --- | --- | --- |
 | `context-overflow` | A run's context overflowed, including a delegated run's | `resolvedModel`: the `IFlexResolvedModel` the model resolver returned for that run, frozen; a delegated run's overflow carries the delegated run's own model |
+| `context-budget` | Settled history exceeds `contextCompactionBytes` before a generation's first inference (256 KiB by default with a compactor) | `resolvedModel`: the exact model resolved for that run, including its delegated model |
 | `manual` | `/compact` or `compactSession()` | `modelHint`: the `modelHint` of the `/compact` execution options or of `compactSession(scopeId, sessionId, { modelHint })`, when one was passed |
 | `retention` | Event retention | none |
 
@@ -1064,6 +1070,8 @@ After every harness using a `JsonFileFlexHarnessStores` instance has been dispos
 
 The JSON stores are explicitly not cross-process safe. When several processes can access the same storage namespace, every core `IFlexHarnessStores` domain and `stores.projectManagement` must use database-backed or equivalent cross-process CAS. Process-local CAS for the core stores or for PM alone is insufficient: session generation creation, cleanup tombstones, PM replacement, and stale-writer rejection must all retain their respective atomic preconditions across processes.
 
+`NoSqlFlexHarnessStores` from `/stores/nosqldb` is that database-backed bundle for every domain. Pass it an initialized `SmartdataDb` and `await stores.prepare()` at startup, before the first harness uses it; the subpath readme describes chunked snapshots and failure reporting.
+
 Direct store operations and non-run session mutations surface conflicts as `FlexHarnessStoreConflictError` or the corresponding AgentSession store conflict. Malformed, wrong-schema, or non-JSON snapshots are surfaced as `FlexHarnessStoreFormatError`. A write or deletion that changed its target but cannot confirm parent-directory durability surfaces `FlexHarnessStoreCommitUncertainError` with the affected path, operation, and cause. Run persistence failures cross the external error boundary and therefore become `FlexHarnessExternalError`. FlexHarness does not merge conflicts.
 
 Each domain serializes its own mutations. A successful run first persists a hidden completed projection, then finalizes the canonical Agent generation as `accepted`, then promotes the hidden projection publicly. Recovery uses the canonical generation outcome to promote an accepted stage or publish a failed/cancelled projection. Failed and cancelled generations remain auditable but never enter future model context.

package/ts/utils.harnessoptions.ts

@@ -380,6 +380,7 @@ export function normalizeAgentSessionPolicy<TScope>(
   return {
     ...(policy.contextBuilder === undefined ? {} : { contextBuilder: policy.contextBuilder }),
     ...(policy.contextCompactor === undefined ? {} : { contextCompactor: policy.contextCompactor }),
+    ...(policy.contextCompactionBytes === undefined ? {} : { contextCompactionBytes: policy.contextCompactionBytes }),
     ...(policy.eventRetention === undefined ? {} : { eventRetention: policy.eventRetention }),
     ...(policy.changeListenerTimeoutMs === undefined
       ? {}

package/ts/utils.storerules.ts

@@ -0,0 +1,177 @@
+import type * as plugins from './plugins.js';
+import {
+  FlexHarnessStoreConflictError,
+  FlexHarnessStoreFormatError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import type {
+  IFlexPermissionSnapshot,
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementTombstone,
+  IFlexProjectManagementWriteContext,
+  IFlexScopeSnapshot,
+  TFlexProjectionSnapshot,
+  TFlexProjectManagementRecord,
+} from './interfaces.js';
+import { assertJsonSerializable, cloneSerializable } from './utils.json.js';
+import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
+
+/**
+ * Store-independent admission rules every `IFlexHarnessStores` implementation applies: argument
+ * validation, the next-revision rule, exact session keys, and the project-management generation
+ * fence. Backends own only how they read, compare and write.
+ */
+
+type TSnapshot =
+  | IFlexScopeSnapshot
+  | TFlexProjectionSnapshot
+  | IFlexPermissionSnapshot
+  | TFlexProjectManagementRecord;
+type TSnapshotValidator<TSnapshotValue extends TSnapshot> = (
+  value: unknown,
+) => asserts value is TSnapshotValue;
+
+export function validateIdentifier(value: string, name: string): void {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new FlexHarnessValidationError(`${name} must be a non-empty string.`);
+  }
+}
+
+export function validateExpectedRevision(expectedRevision: number): void {
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+    throw new FlexHarnessValidationError('expectedRevision must be a non-negative integer.');
+  }
+}
+
+export function validateProjectManagementWriteContext(
+  writeContext: IFlexProjectManagementWriteContext,
+): void {
+  assertJsonSerializable(writeContext, '$writeContext');
+  assertRecord(writeContext, 'writeContext');
+  assertExactKeys(writeContext, ['actor', 'runId', 'agent', 'toolCallId'], 'writeContext');
+  if (writeContext.actor !== 'agent' && writeContext.actor !== 'application') {
+    throw new FlexHarnessValidationError('writeContext.actor must be agent or application.');
+  }
+  for (const key of ['runId', 'agent', 'toolCallId'] as const) {
+    if (writeContext[key] !== undefined) validateIdentifier(writeContext[key], `writeContext.${key}`);
+  }
+}
+
+export function validateSnapshotSave<TSnapshotValue extends TSnapshot>(
+  snapshot: TSnapshotValue,
+  expectedRevision: number,
+  validator: TSnapshotValidator<TSnapshotValue>,
+): TSnapshotValue {
+  validator(snapshot);
+  validateExpectedRevision(expectedRevision);
+  if (snapshot.revision !== expectedRevision + 1) {
+    throw new FlexHarnessStoreFormatError(
+      `Snapshot revision ${snapshot.revision} must equal expected revision ${expectedRevision} plus one.`,
+    );
+  }
+  return cloneSerializable(snapshot);
+}
+
+export function providerKey(storageKey: string, sessionId: string): string {
+  validateIdentifier(storageKey, 'storageKey');
+  validateIdentifier(sessionId, 'sessionId');
+  return JSON.stringify([storageKey, sessionId]);
+}
+
+export function assertProjectionSession(snapshot: TFlexProjectionSnapshot, sessionId: string): void {
+  for (const message of snapshot.messages) {
+    if (message.sessionId !== sessionId) {
+      throw new FlexHarnessStoreFormatError(
+        `Projection message "${message.messageId}" does not belong to session "${sessionId}".`,
+      );
+    }
+  }
+  for (const terminal of snapshot.stagedTerminals) {
+    if (
+      terminal.userMessage.sessionId !== sessionId
+      || terminal.assistantMessage.sessionId !== sessionId
+    ) {
+      throw new FlexHarnessStoreFormatError(
+        `Staged terminal "${terminal.runId}" does not belong to session "${sessionId}".`,
+      );
+    }
+  }
+}
+
+function sameProjectManagementGeneration(
+  left: TFlexProjectManagementRecord,
+  right: TFlexProjectManagementRecord,
+): boolean {
+  return left.sessionGenerationId === right.sessionGenerationId
+    && left.sessionGenerationSequence === right.sessionGenerationSequence;
+}
+
+function canInitializeProjectManagementGeneration(
+  current: TFlexProjectManagementRecord,
+  next: TFlexProjectManagementRecord,
+  expectedRevision: number,
+): boolean {
+  return 'deletedAt' in current
+    && expectedRevision === 0
+    && next.sessionGenerationId !== current.sessionGenerationId
+    && next.sessionGenerationSequence > current.sessionGenerationSequence;
+}
+
+/**
+ * Admits a live project-management save over the stored record: a CAS save within the stored
+ * generation, or a newer generation that replaces a tombstone at expected revision 0.
+ */
+export function assertProjectManagementSaveAdmitted(
+  key: string,
+  current: TFlexProjectManagementRecord | undefined,
+  snapshot: IFlexProjectManagementSnapshot,
+  expectedRevision: number,
+): void {
+  const actualRevision = current?.revision ?? 0;
+  if (current && !sameProjectManagementGeneration(current, snapshot)) {
+    if (!canInitializeProjectManagementGeneration(current, snapshot, expectedRevision)) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+  } else if ((current && 'deletedAt' in current) || actualRevision !== expectedRevision) {
+    throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+  }
+}
+
+/**
+ * Admits a project-management tombstone over the stored record. Returns false when the same
+ * generation is already tombstoned, which makes a repeated cleanup idempotent.
+ */
+export function isProjectManagementTombstoneAdmitted(
+  key: string,
+  current: TFlexProjectManagementRecord | undefined,
+  tombstone: IFlexProjectManagementTombstone,
+  expectedRevision: number,
+): boolean {
+  const actualRevision = current?.revision ?? 0;
+  if (current && sameProjectManagementGeneration(current, tombstone)) {
+    if ('deletedAt' in current) return false;
+    if (actualRevision !== expectedRevision) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+  } else if (current) {
+    if (!canInitializeProjectManagementGeneration(current, tombstone, expectedRevision)) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+  } else if (actualRevision !== expectedRevision) {
+    throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+  }
+  return true;
+}
+
+/** An archive is written once; repeating it with the same events is a no-op. */
+export function assertSameArchiveEvents(
+  existing: plugins.IAgentEventArchiveV2,
+  next: plugins.IAgentEventArchiveV2,
+): void {
+  if (
+    JSON.stringify(existing.events.map((event) => event.id))
+    !== JSON.stringify(next.events.map((event) => event.id))
+  ) {
+    throw new Error(`Archive "${next.archiveId}" already exists with different events.`);
+  }
+}

package/ts_chat_harness/classes.transcript.ts

@@ -0,0 +1,365 @@
+import type * as plugins from './plugins.js';
+import type {
+  IFlexMessage,
+  IFlexPermissionRequest,
+  IFlexProjectStateResult,
+  IFlexSession,
+  TFlexHarnessEvent,
+  TFlexMessagePart,
+} from '../ts/interfaces.js';
+import {
+  flexMessageToHarnessRows,
+  flexPartRowId,
+  flexPartTimingKey,
+  flexPermissionToHarness,
+  flexProjectToHarnessScratchpad,
+  flexProjectToHarnessTodos,
+  flexSessionToHarnessStatus,
+  flexToolPartToHarness,
+  flexUsageToHarness,
+  type IFlexPartTiming,
+} from './functions.mapping.js';
+
+export interface IFlexHarnessTranscriptOptions {
+  scopeId: string;
+  sessionId: string;
+}
+
+/** What `load()` reads: the session's authoritative state, as the harness APIs return it. */
+export interface IFlexHarnessTranscriptSnapshot {
+  /** `getMessages()` of the session. */
+  messages: readonly IFlexMessage[];
+  /** `listPendingPermissions()` of the session. */
+  permissions?: readonly IFlexPermissionRequest[];
+  /** `getSession()`; states whether a run is active or failed. */
+  session?: IFlexSession;
+  /** `getProjectState()`, when project management is enabled. */
+  project?: IFlexProjectStateResult;
+}
+
+/** The inputs of `dees-harness-chat`, as plain data the transcript does not share. */
+export interface IFlexHarnessTranscriptView {
+  messages: plugins.IHarnessMessage[];
+  permissions: plugins.IHarnessPermissionRequest[];
+  /** FlexHarness asks no questions; always empty. */
+  questions: plugins.IHarnessQuestionRequest[];
+  status: plugins.IHarnessStatus;
+  usage: plugins.IHarnessUsage;
+  todos: plugins.IHarnessTodoItem[];
+  scratchpad?: plugins.IHarnessScratchpad;
+}
+
+/** Where an event stands in its harness instance's event stream, as the host received it. */
+export interface IFlexHarnessEventDelivery {
+  /**
+   * The `sequence` of the event of the same harness instance the host received just before this
+   * one, of any session; `undefined` for the first event after `load()`. The host forwards every
+   * event of the instance in order, and calls `load()` after a gap or a reconnect.
+   */
+  precedingSequence: number | undefined;
+}
+
+/**
+ * What one event changed. Apply `deltas` with `applyDelta()` in order; when `messages` is true,
+ * assign `transcript.view().messages` instead, which already holds the deltas. `reload` means
+ * the transcript can no longer follow the session incrementally: read the session again and
+ * pass it to `load()`.
+ */
+export interface IFlexHarnessTranscriptChange {
+  messages: boolean;
+  deltas: plugins.THarnessStreamDelta[];
+  permissions: boolean;
+  status: boolean;
+  usage: boolean;
+  reload: boolean;
+}
+
+const utf8 = new TextEncoder();
+
+/** UTF-8 bytes `delta` adds to `text`, counted the way FlexHarness counts them. */
+function appendedUtf8Bytes(text: string, delta: string): number {
+  const trailing = text.charCodeAt(text.length - 1);
+  const leading = delta.charCodeAt(0);
+  const joinsSurrogatePair = trailing >= 0xd800 && trailing <= 0xdbff
+    && leading >= 0xdc00 && leading <= 0xdfff;
+  return utf8.encode(delta).length - (joinsSurrogatePair ? 2 : 0);
+}
+
+function sumUsage(
+  total: plugins.IHarnessUsage,
+  usage: plugins.IHarnessUsage,
+): plugins.IHarnessUsage {
+  const sum = (key: keyof plugins.IHarnessUsage) => (total[key] ?? 0) + (usage[key] ?? 0);
+  return {
+    inputTokens: sum('inputTokens'),
+    outputTokens: sum('outputTokens'),
+    totalTokens: sum('totalTokens'),
+    cacheReadTokens: sum('cacheReadTokens'),
+    cacheWriteTokens: sum('cacheWriteTokens'),
+  };
+}
+
+const noChange = (): IFlexHarnessTranscriptChange => ({
+  messages: false,
+  deltas: [],
+  permissions: false,
+  status: false,
+  usage: false,
+  reload: false,
+});
+
+/**
+ * Follows one FlexHarness session and keeps the `dees-harness-chat` inputs for it. It is a pure
+ * reducer over the session's public messages and events: it imports no runtime code, so it runs
+ * in the browser beside the components as well as on the server beside the harness.
+ */
+export class FlexHarnessTranscript {
+  public readonly scopeId: string;
+  public readonly sessionId: string;
+  private flexMessages: IFlexMessage[] = [];
+  private readonly timings = new Map<string, IFlexPartTiming>();
+  private readonly partBytes = new Map<string, number>();
+  private readonly permissionRows = new Map<string, plugins.IHarnessPermissionRequest>();
+  private status: plugins.IHarnessStatus = { type: 'idle' };
+  private usage: plugins.IHarnessUsage = {};
+  private todos: plugins.IHarnessTodoItem[] = [];
+  private scratchpad?: plugins.IHarnessScratchpad;
+  private runningQueueId?: string;
+
+  constructor(options: IFlexHarnessTranscriptOptions) {
+    this.scopeId = options.scopeId;
+    this.sessionId = options.sessionId;
+  }
+
+  /** The queue entry whose run is running; a steer joins it. */
+  public get activeQueueId(): string | undefined {
+    return this.runningQueueId;
+  }
+
+  /** Replaces everything with the session's authoritative state. */
+  public load(snapshot: IFlexHarnessTranscriptSnapshot): void {
+    this.flexMessages = [];
+    this.todos = [];
+    this.scratchpad = undefined;
+    this.runningQueueId = undefined;
+    this.timings.clear();
+    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.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,
+      {},
+    );
+    if (snapshot.project) this.applyProjectState(snapshot.project);
+  }
+
+  /** Takes in the session's task list and scratchpad after `getProjectState()`. */
+  public applyProjectState(project: IFlexProjectStateResult): void {
+    this.todos = flexProjectToHarnessTodos(project);
+    this.scratchpad = flexProjectToHarnessScratchpad(this.sessionId, project);
+  }
+
+  /** A copy of the component inputs; the transcript keeps its own objects. */
+  public view(): IFlexHarnessTranscriptView {
+    return structuredClone({
+      messages: this.flexMessages.flatMap((message, index) =>
+        flexMessageToHarnessRows(message, index, this.timings)),
+      permissions: [...this.permissionRows.values()],
+      questions: [],
+      status: this.status,
+      usage: this.usage,
+      todos: this.todos,
+      ...(this.scratchpad === undefined ? {} : { scratchpad: this.scratchpad }),
+    });
+  }
+
+  /**
+   * 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.
+   */
+  public applyEvent(
+    event: TFlexHarnessEvent,
+    delivery: IFlexHarnessEventDelivery,
+  ): IFlexHarnessTranscriptChange {
+    const change = noChange();
+    if (
+      delivery.precedingSequence !== undefined
+      && event.sequence !== delivery.precedingSequence + 1
+    ) {
+      change.reload = true;
+      return change;
+    }
+    if (event.scopeId !== this.scopeId || event.sessionId !== this.sessionId) return change;
+    const timestamp = Date.parse(event.timestamp);
+    switch (event.type) {
+      case 'session.created':
+      case 'session.updated':
+        this.setStatus(change, flexSessionToHarnessStatus(event.session));
+        break;
+      case 'session.deleted':
+        this.load({ messages: [] });
+        change.messages = change.permissions = change.status = change.usage = true;
+        break;
+      case 'run.started':
+        this.setStatus(change, { type: 'busy' });
+        break;
+      case 'message.created':
+      case 'message.updated':
+        this.upsertMessage(event.message);
+        change.messages = true;
+        break;
+      case 'part.started':
+        this.timings.set(flexPartTimingKey(event.messageId, event.partId), { startedAt: timestamp });
+        this.applyPartSnapshot(change, event.messageId, event.partIndex, event.part);
+        break;
+      case 'part.updated':
+        this.applyPartSnapshot(change, event.messageId, event.partIndex, event.part);
+        break;
+      case 'part.completed': {
+        const key = flexPartTimingKey(event.messageId, event.partId);
+        this.timings.set(key, { ...this.timings.get(key), endedAt: timestamp });
+        this.applyPartSnapshot(change, event.messageId, event.partIndex, event.part);
+        break;
+      }
+      case 'part.delta':
+        this.applyPartDelta(change, event);
+        break;
+      case 'permission.requested':
+        this.permissionRows.set(event.request.permissionId, flexPermissionToHarness(event.request));
+        change.permissions = true;
+        break;
+      case 'permission.resolved': {
+        const row = this.permissionRows.get(event.request.permissionId);
+        if (!row) break;
+        row.response = event.decision;
+        row.respondedAt = timestamp;
+        change.permissions = true;
+        break;
+      }
+      case 'run.finished':
+        this.upsertMessage(event.message);
+        change.messages = true;
+        if (event.message.usage) {
+          this.usage = sumUsage(this.usage, flexUsageToHarness(event.message.usage));
+          change.usage = true;
+        }
+        this.setStatus(change, event.status === 'failed'
+          ? { type: 'error', ...(event.error ? { message: event.error.message } : {}) }
+          : { type: 'idle' });
+        break;
+      case 'prompt.started':
+      case 'prompt.running':
+        this.runningQueueId = event.queueId;
+        break;
+      case 'prompt.finished':
+        if (this.runningQueueId === event.queueId) this.runningQueueId = undefined;
+        break;
+      case 'session.history.changed':
+        change.reload = true;
+        break;
+      default:
+        break;
+    }
+    return change;
+  }
+
+  private setStatus(change: IFlexHarnessTranscriptChange, status: plugins.IHarnessStatus): void {
+    if (status.type === this.status.type && status.message === this.status.message) return;
+    this.status = status;
+    change.status = true;
+  }
+
+  private upsertMessage(message: IFlexMessage): void {
+    const index = this.flexMessages.findIndex((entry) => entry.messageId === message.messageId);
+    const copy = structuredClone(message);
+    if (index === -1) this.flexMessages.push(copy);
+    else this.flexMessages[index] = copy;
+    for (const part of copy.parts) {
+      if (part.type === 'text' || part.type === 'reasoning') {
+        this.partBytes.set(flexPartTimingKey(copy.messageId, part.partId), utf8.encode(part.text).length);
+      }
+    }
+  }
+
+  private applyPartSnapshot(
+    change: IFlexHarnessTranscriptChange,
+    messageId: string,
+    partIndex: number,
+    part: TFlexMessagePart,
+  ): void {
+    const message = this.flexMessages.find((entry) => entry.messageId === messageId);
+    if (!message || partIndex > message.parts.length) {
+      change.reload = true;
+      return;
+    }
+    const previous = message.parts[partIndex];
+    message.parts[partIndex] = structuredClone(part);
+    const key = flexPartTimingKey(messageId, part.partId);
+    if (part.type === 'text' || part.type === 'reasoning') {
+      this.partBytes.set(key, utf8.encode(part.text).length);
+    }
+    const rowId = flexPartRowId(messageId, part.partId);
+    if (previous?.partId !== part.partId || previous.type !== part.type) {
+      change.messages = true;
+      return;
+    }
+    if (part.type === 'tool') {
+      change.deltas.push({
+        type: 'tool-update',
+        messageId: rowId,
+        tool: flexToolPartToHarness(part, this.timings.get(key)),
+      });
+    } else if (part.type === 'text' && previous.type === 'text') {
+      if (previous.text !== part.text) change.messages = true;
+      else if (message.status !== 'streaming' || partIndex !== message.parts.length - 1) {
+        change.deltas.push({ type: 'message-end', messageId: rowId });
+      }
+    } else if (part.type === 'reasoning' && previous.type === 'reasoning') {
+      if (previous.text !== part.text) change.messages = true;
+      else if (part.status !== 'running') {
+        change.deltas.push({
+          type: 'reasoning-end',
+          messageId: rowId,
+          partId: part.partId,
+          endedAt: this.timings.get(key)?.endedAt,
+        });
+      }
+    } else {
+      change.messages = true;
+    }
+  }
+
+  private applyPartDelta(
+    change: IFlexHarnessTranscriptChange,
+    event: Extract<TFlexHarnessEvent, { type: 'part.delta' }>,
+  ): void {
+    const message = this.flexMessages.find((entry) => entry.messageId === event.messageId);
+    const part = message?.parts[event.partIndex];
+    const key = flexPartTimingKey(event.messageId, event.partId);
+    if (
+      !part
+      || part.partId !== event.partId
+      || part.type !== event.partType
+      || this.partBytes.get(key) !== event.baseTextUtf8Bytes
+    ) {
+      change.reload = true;
+      return;
+    }
+    const bytes = event.baseTextUtf8Bytes + appendedUtf8Bytes(part.text, event.delta);
+    if (bytes !== event.textUtf8Bytes) {
+      change.reload = true;
+      return;
+    }
+    part.text += event.delta;
+    this.partBytes.set(key, bytes);
+    const rowId = flexPartRowId(event.messageId, event.partId);
+    change.deltas.push(event.partType === 'text'
+      ? { type: 'text', messageId: rowId, delta: event.delta }
+      : { type: 'reasoning', messageId: rowId, partId: event.partId, delta: event.delta });
+  }
+}