@modelprofile.com/flexharness 3.7.0 → 3.8.0

package/readme.md

@@ -282,6 +282,8 @@ await harness.reconcileToolExecution(scopeId, sessionId, intentId, {
   resolution: 'executed',
   output: { committed: true },
 });
+const reversion = await harness.getSessionReversionInfo(scopeId, sessionId);
+console.log(reversion.undoAvailable, reversion.redoAvailable, reversion.groups);
 const undone = await harness.undoSession(scopeId, sessionId);
 console.log(undone.revertedRunId);
 const redone = await harness.redoSession(scopeId, sessionId);
@@ -351,12 +353,14 @@ const harness = new FlexHarness({
 
 At most 128 custom commands may be registered. Every registration must be a plain object with exactly one of `template` or `handler`; names must match `[a-z][a-z0-9-]{0,63}`, be unique, and not use a reserved name. Optional descriptions must be non-empty and at most 2048 UTF-8 bytes. Templates must be non-empty and at most 768 KiB, and the expanded prompt must also fit 768 KiB. Registrations are copied and frozen during construction.
 
-`/undo` and `/redo`, plus `undoSession()` and `redoSession()`, move a durable transcript 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.
+`/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 undo boundary. Failed and cancelled turns after it belong to that unit; failed or cancelled turns before the first completion belong to the first completed unit. Undo applies the unit's 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.
 
 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.
 
+Session metadata archival through `updateSession(..., { archived: true })` only sets `archivedAt`. It does not archive Agent events, retire captures, or remove undo history.
+
 `executeSlashCommand()` is the authoritative parser and lookup boundary. Its result distinguishes `not-command`, `malformed`, `unknown`, completed `operation`, bounded `handler-result`, and `prompt-admission`. A prompt admission contains the normal `{ queueId, runId, completion }`; await `admission.completion` for the model result. Unknown commands are never admitted as literal prompts. Known unavailable commands and invalid arguments throw typed FlexHarness errors. Options accept `modelHint`, `system`, `maxSteps`, and `signal`; commands do not accept attachments. Aborting a template or `init` execution cancels its exact queued or started prompt without affecting another queue entry.
 
 Templates replace every `$ARGUMENTS` with untouched raw argument text. `$1` through the highest referenced positional placeholder use tokenized arguments, with the highest position receiving all remaining tokens joined by spaces. Missing positions become empty. A template with no placeholders appends non-empty raw arguments after a blank line. `/init` uses the OpenCode 1.18.15 `AGENTS.md` initialization prompt with provider-neutral active-workspace wording.
@@ -365,7 +369,9 @@ Handler context is frozen and contains only the resolved scope identity, session
 
 ### Workspace Reversion Provider
 
-Applications that also need workspace rollback provide all six `IFlexTurnReversionProvider` operations:
+`reversionPolicy` defaults to `transcript-optional`, preserving the V1 behavior described above. Set it to `workspace-required` when transcript and workspace traversal must move together. This policy requires an `IFlexTurnReversionProviderV2` at construction.
+
+Applications using the original protocol can continue to provide all six unchanged `IFlexTurnReversionProvider` operations:
 
 ```typescript
 import type { IFlexTurnReversionProvider } from '@modelprofile.com/flexharness';
@@ -380,17 +386,85 @@ const turnReversionProvider: IFlexTurnReversionProvider<IProjectScope> = {
 };
 ```
 
+Protocol 2 adds the `protocolVersion` discriminant and a tagged finalized outcome. The prepare, apply, apply-inspection, and release contexts remain the V1 shapes:
+
+```typescript
+import type {
+  IFlexTurnReversionProviderV2,
+} from '@modelprofile.com/flexharness';
+
+const turnReversionProvider: IFlexTurnReversionProviderV2<IProjectScope> = {
+  protocolVersion: 2,
+  prepare: (context) => workspaceHistory.prepare(context),
+  inspectCapture: (context) => workspaceHistory.inspectCapture(context),
+  async finalize(context) {
+    const capture = await workspaceHistory.finalize(context);
+    if (capture.changedPaths.length === 0) {
+      return {
+        disposition: 'no-change',
+        reference: capture.cleanupReference,
+      };
+    }
+    if (!capture.revertible) {
+      return {
+        disposition: 'nonrevertible',
+        reference: capture.cleanupReference,
+        reasonCode: 'git.unmerged',
+        affectedWorkspaces: [{ id: capture.workspaceId, label: capture.workspaceLabel }],
+      };
+    }
+    return {
+      disposition: 'revertible',
+      reference: capture.reference,
+      affectedWorkspaces: [{ id: capture.workspaceId, label: capture.workspaceLabel }],
+    };
+  },
+  inspectApply: (context) => workspaceHistory.inspectApply(context),
+  apply: (context) => workspaceHistory.apply(context),
+  release: (context) => workspaceHistory.release(context),
+};
+
+const harness = new FlexHarness<IProjectScope>({
+  // scopeResolver, modelResolver, stores, and other options...
+  turnReversionProvider,
+  reversionPolicy: 'workspace-required',
+});
+```
+
+V1 `finalize()` returns a JSON reference, and a finalized V1 `inspectCapture()` result is `{ status: 'finalized', reference }`. V2 `finalize()` returns `revertible`, `no-change`, or `nonrevertible`, and a finalized V2 inspection is `{ status: 'finalized', outcome }` with the same complete tagged outcome. Every V2 outcome carries a normalized cleanup reference. A revertible outcome also carries `affectedWorkspaces`. A no-change outcome omits that list or supplies an empty list. A nonrevertible outcome carries a stable `reasonCode` and may carry affected workspaces.
+
+Affected workspace descriptors contain only stable, non-whitespace `id` and display `label` strings. A result accepts at most 64 unique descriptors; IDs are limited to 512 UTF-8 bytes, labels to 2048 bytes, and reason codes to 128 bytes matching `[A-Za-z0-9][A-Za-z0-9._-]*`. References use the configured JSON normalization depth and byte limit with an absolute 256 KiB cap.
+
+Controllers query safe history metadata with one method:
+
+```typescript
+const info = await harness.getSessionReversionInfo(scopeId, sessionId);
+for (const group of info.groups) {
+  console.log(
+    group.runId,
+    group.kind,
+    group.visibility,
+    group.affectedWorkspaces,
+    group.affectedWorkspacesTruncated,
+  );
+}
+```
+
+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`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, deterministic per-segment `operationId`, and `direction`; release contexts contain the reference.
 
 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`. `finalized` includes the reference. `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 reference. 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.
-4. Before undo or redo, FlexHarness persists an apply write-ahead record. `inspectApply()` returns `not-applied`, `applied`, or `unknown`. FlexHarness calls `apply()` only for `not-applied`; after an apply error it inspects again before deciding whether to retry or fence. 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. Providers should treat `operationId` idempotently.
-5. `release()` relinquishes the capture after 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.
+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.
+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.
+
+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.
 
-Inspection, recovery, finalization, and release use fresh maintenance signals bounded by `agentSessionPolicy.generationLeaseCleanupTimeoutMs`, which defaults to 30 seconds. Providers must observe every supplied signal and must serialize ownership for a storage namespace. The same provider capability must remain configured whenever a capture-backed session is reopened, retired, disposed, or deleted. Capture-backed recovery and deletion fail closed without it.
+Inspection, recovery, finalization, and release use fresh maintenance signals bounded by `agentSessionPolicy.generationLeaseCleanupTimeoutMs`, which defaults to 30 seconds. Providers must observe every supplied signal and must serialize ownership for a storage namespace. A provider with the matching persisted `protocolVersion` must remain configured whenever a capture-backed session is reopened, retired, disposed, or deleted. Capture-backed recovery and deletion fail closed without it.
 
 Workspace reversion is generic and application-defined. It does not reverse network, database, billing, or other side effects unless the provider deliberately captures them. References are normalized with `toolOutputLimits` and have an absolute 256 KiB encoded cap.
 
@@ -539,7 +613,9 @@ Direct store operations and non-run session mutations surface conflicts as `Flex
 
 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.
 
-Projection stores accept schema version 1 or 2 from `load()`, but every `save()` receives the current schema-2 shape. A loaded schema-1 projection is treated as having no reversion segments, cursor, exclusions, pending operation, or pending releases; its next projection mutation upgrades it to schema 2. Custom stores must preserve strict compare-and-swap revisions across that read-upgrade-write cycle. Existing schema-1 messages remain visible but are not retroactively made undoable.
+Projection stores accept schema version 1, 2, or 3 from `load()`, but every `save()` receives the current schema-3 shape. Schema 3 records explicit reversion protocol, transcript/workspace provenance, and V2 disposition. A terminal V2 segment must be conclusively `revertible`, `no-change`, or `nonrevertible`; a pending V2 capture remains owned by its capture WAL and is never treated as transcript history.
+
+A loaded schema-1 projection has no reversion state. Schema-2 `workspaceCaptured` segments migrate as protocol-1 workspace/revertible history without discarding references; transcript-only segments migrate as protocol-1 transcript provenance. Under `workspace-required`, that legacy transcript history is a barrier. The next projection mutation writes schema 3. Custom stores must preserve strict compare-and-swap revisions across schema-1 and schema-2 read-upgrade-write cycles, including uncertain-save reconciliation.
 
 ## Migrating From 2.x
 
@@ -563,7 +639,7 @@ const stores = new JsonFileFlexHarnessStores({
 await migrateLegacyFlexHarnessSnapshot(storageKey, legacySnapshot, stores);
 ```
 
-`loadLegacySnapshot()` is application-owned access to the snapshot written by the `2.x` store. The migration validates the complete source and every public run before writing. A run left streaming by a process crash is deterministically repaired to the same cancelled state that the `2.x` loader produced in memory. The migration then converts private model messages into generationless canonical Agent conversation events, records terminal SmartAgent transactions for completed, failed, and cancelled public runs, and writes schema-2 projections with empty reversion state. Migrated history therefore remains visible and auditable but is not retroactively undoable; turns created after migration receive normal reversion segments and optional workspace captures. The migration preflights the scope, projection, permission, Agent event, and job destinations before any write, applies missing per-session domains first, and publishes scope discovery last. It is safe to rerun after no work, a completed prefix, or a complete migration when existing destination content is identical. It fails closed when a destination contains conflicting content or non-empty jobs. Keep the legacy snapshot until the migrated application has loaded and verified every storage namespace.
+`loadLegacySnapshot()` is application-owned access to the snapshot written by the `2.x` store. The migration validates the complete source and every public run before writing. A run left streaming by a process crash is deterministically repaired to the same cancelled state that the `2.x` loader produced in memory. The migration then converts private model messages into generationless canonical Agent conversation events, records terminal SmartAgent transactions for completed, failed, and cancelled public runs, and writes schema-3 projections with empty reversion state. Migrated history therefore remains visible and auditable but is not retroactively undoable; turns created after migration receive normal reversion segments and optional workspace captures. The migration preflights the scope, projection, permission, Agent event, and job destinations before any write, applies missing per-session domains first, and publishes scope discovery last. It is safe to rerun after no work, a completed prefix, or a complete migration when existing destination content is identical. It fails closed when a destination contains conflicting content or non-empty jobs. Keep the legacy snapshot until the migrated application has loaded and verified every storage namespace.
 
 ## Shutdown
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '3.7.0',
+  version: '3.8.0',
   description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
 }