@modelprofile.com/flexharness 18.9.1 → 18.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -34,6 +34,7 @@ import type {
34
34
  IFlexScopeLoadMetrics,
35
35
  IFlexScopeSnapshot,
36
36
  IFlexSession,
37
+ IFlexSessionAuxiliarySummary,
37
38
  IFlexSessionImportLimits,
38
39
  IFlexSessionTombstone,
39
40
  IFlexSubagentDefinition,
@@ -66,6 +67,7 @@ import { FlexTimeSlicer } from './classes.timeslicer.js';
66
67
  import { liveScopeSessions, normalizeScopeSnapshot } from './utils.scopesnapshot.js';
67
68
  import { hydrateAgentMessages } from './utils.prompt.js';
68
69
  import { createProjectionChange, freezeProjectionEntries } from './utils.projectionchange.js';
70
+ import { assertFlexSessionAuxiliarySummary, deriveReversionPresentation } from './utils.reversionpresentation.js';
69
71
  import {
70
72
  normalizeAgentSessionPolicy,
71
73
  normalizeAttachmentResolver,
@@ -98,6 +100,7 @@ import { validateIdentifier, validateProjectedErrorInfo } from './utils.validati
98
100
  import {
99
101
  createSessionMetricsOperation,
100
102
  createSessionMetricsState,
103
+ sessionMetricsView,
101
104
  } from './utils.sessionmetrics.js';
102
105
  import type {
103
106
  TCanonicalOutcome,
@@ -985,6 +988,165 @@ export class FlexHarnessCore<TScope> {
985
988
  });
986
989
  }
987
990
 
991
+ /** Reads an exact-head auxiliary summary without acquiring a session runtime. */
992
+ public readGuardedCleanSessionAuxiliarySummary(
993
+ state: IStorageState,
994
+ sessionId: string,
995
+ ): Promise<IFlexSessionAuxiliarySummary | undefined> {
996
+ const local = this.stores.scopes.sessionLocal;
997
+ const projectionStore = this.stores.projections;
998
+ if (!state.sessionLocal || !this.cleanRecoveryEnabled(state.storageKey)
999
+ || !local?.readCleanSessionProof || !projectionStore.loadHead
1000
+ || !projectionStore.loadAuxiliarySummaryHead || !this.stores.agentEvents.loadHead) {
1001
+ return Promise.resolve(undefined);
1002
+ }
1003
+ return this.withRecoveryPublication(state, sessionId, async () => {
1004
+ const current = state.catalogue.get(sessionId);
1005
+ if (!current || state.tombstones.has(sessionId) || state.initializingSessions.has(sessionId)) return undefined;
1006
+ const proof = await local.readCleanSessionProof!(state.storageKey, sessionId);
1007
+ if (!proof) {
1008
+ if (!state.recoverySessionIds.has(sessionId)) {
1009
+ const catalogue = await local.loadCatalogue(state.storageKey);
1010
+ if (!catalogue.qualified) throw new FlexHarnessStoreFormatError('Session recovery proof became unqualified.');
1011
+ await this.markRecoveryRequired(state, sessionId);
1012
+ }
1013
+ return undefined;
1014
+ }
1015
+ if (flexSessionDigest(proof.session) !== flexSessionDigest(current)) {
1016
+ await this.markRecoveryRequired(state, sessionId);
1017
+ return undefined;
1018
+ }
1019
+ const matches = (actual: { incarnationId?: string; revision: number; contentRoot: string } | undefined,
1020
+ expected: { incarnationId: string; revision: number; contentRoot: string }) =>
1021
+ actual?.incarnationId === expected.incarnationId
1022
+ && actual.revision === expected.revision
1023
+ && actual.contentRoot === expected.contentRoot;
1024
+ const [projection, agentEvents] = await Promise.all([
1025
+ projectionStore.loadHead!(state.storageKey, sessionId),
1026
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1027
+ ]);
1028
+ if (!matches(projection, proof.clean.projection) || !matches(agentEvents, proof.clean.agentEvents)) {
1029
+ await this.markRecoveryRequired(state, sessionId);
1030
+ return undefined;
1031
+ }
1032
+ const read = await projectionStore.loadAuxiliarySummaryHead!(
1033
+ state.storageKey, sessionId, this.reversionPolicy === 'workspace-required',
1034
+ );
1035
+ if (!read || !matches(read.projection, proof.clean.projection)) return undefined;
1036
+ // A clean sidecar and both exact heads must still match after the summary read settles.
1037
+ const [settledProof, settledProjection, settledAgentEvents] = await Promise.all([
1038
+ local.readCleanSessionProof!(state.storageKey, sessionId),
1039
+ projectionStore.loadHead!(state.storageKey, sessionId),
1040
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1041
+ ]);
1042
+ if (!settledProof || flexSessionDigest(settledProof.session) !== flexSessionDigest(current)
1043
+ || !matches(settledProof.clean.projection, proof.clean.projection)
1044
+ || !matches(settledProof.clean.agentEvents, proof.clean.agentEvents)
1045
+ || !matches(settledProjection, proof.clean.projection)
1046
+ || !matches(settledAgentEvents, proof.clean.agentEvents)) return undefined;
1047
+ const latest = state.catalogue.get(sessionId);
1048
+ if (!latest || state.tombstones.has(sessionId)
1049
+ || flexSessionDigest(latest) !== flexSessionDigest(current)) return undefined;
1050
+ return assertFlexSessionAuxiliarySummary(read.summary);
1051
+ });
1052
+ }
1053
+
1054
+ /** Uses a proved bounded summary or coalesces the target's ordinary hydration. */
1055
+ public async readSessionAuxiliarySource(
1056
+ scopeId: string,
1057
+ sessionId: string,
1058
+ signal?: AbortSignal,
1059
+ ): Promise<{ summary: IFlexSessionAuxiliarySummary; stored?: never }
1060
+ | { summary?: never; stored: IStoredSessionState }> {
1061
+ const throwIfAborted = () => {
1062
+ if (signal?.aborted) throw signal.reason ?? new FlexHarnessAbortError('The session read was aborted.');
1063
+ };
1064
+ throwIfAborted();
1065
+ let onAbort: (() => void) | undefined;
1066
+ const aborted = signal === undefined ? undefined : new Promise<never>((_resolve, reject) => {
1067
+ onAbort = () => reject(signal.reason ?? new FlexHarnessAbortError('The session read was aborted.'));
1068
+ signal.addEventListener('abort', onAbort, { once: true });
1069
+ });
1070
+ const wait = <TValue>(pending: Promise<TValue>): Promise<TValue> =>
1071
+ aborted ? Promise.race([pending, aborted]) : pending;
1072
+ try {
1073
+ const { state, scope } = await wait(this.resolveState(
1074
+ scopeId, this.cleanRecoveryConfigured ? undefined : sessionId,
1075
+ ));
1076
+ throwIfAborted();
1077
+ await wait(this.sessionReadBarrier(state, sessionId));
1078
+ throwIfAborted();
1079
+ this.assertStateAcceptingWork(state);
1080
+ if (state.initializingSessions.has(sessionId)) this.requireSession(state, sessionId);
1081
+ let hydratedForSummary = false;
1082
+ if (!state.sessions.has(sessionId)) {
1083
+ const summary = await wait(this.readGuardedCleanSessionAuxiliarySummary(state, sessionId));
1084
+ throwIfAborted();
1085
+ if (summary) return { summary };
1086
+ await wait(this.hydrateSession(state, sessionId, scopeId, scope.scope));
1087
+ throwIfAborted();
1088
+ hydratedForSummary = true;
1089
+ }
1090
+ const stored = this.requireSession(state, sessionId);
1091
+ await wait(stored.projectionQueue);
1092
+ throwIfAborted();
1093
+ this.assertStateAcceptingWork(state);
1094
+ if (hydratedForSummary) {
1095
+ await wait(this.populateSettledAuxiliarySummary(state, sessionId));
1096
+ throwIfAborted();
1097
+ }
1098
+ return { stored };
1099
+ } finally {
1100
+ if (signal && onAbort) signal.removeEventListener('abort', onAbort);
1101
+ }
1102
+ }
1103
+
1104
+ /** Backfills a missing summary after exact hydration of an already clean session. */
1105
+ private async populateSettledAuxiliarySummary(state: IStorageState, sessionId: string): Promise<void> {
1106
+ const local = this.stores.scopes.sessionLocal;
1107
+ const projections = this.stores.projections;
1108
+ if (!state.sessionLocal || !this.cleanRecoveryEnabled(state.storageKey)
1109
+ || !local?.readCleanSessionProof || !projections.loadHead
1110
+ || !projections.loadAuxiliarySummaryHead || !projections.saveAuxiliarySummaryHead
1111
+ || !this.stores.agentEvents.loadHead) return;
1112
+ if (!this.recoveryProducerGate(state, sessionId).canPublish) return;
1113
+ await this.withRecoveryPublication(state, sessionId, async () => {
1114
+ const stored = state.sessions.get(sessionId);
1115
+ if (!stored || stored.recovering || stored.projectionReconciliationRequired
1116
+ || stored.metricsFailure !== undefined || state.initializingSessions.has(sessionId)
1117
+ || state.tombstones.has(sessionId) || state.activeRuns.has(sessionId)
1118
+ || stored.outstandingPromptsById.size > 0 || stored.pendingReversion !== undefined
1119
+ || stored.pendingReversionReleases.length > 0 || stored.stagedTerminals.length > 0
1120
+ || stored.metrics.pendingGenerationId !== undefined
1121
+ || stored.metrics.pendingCompactionId !== undefined
1122
+ || [...state.pendingPermissions.values()].some((permission) =>
1123
+ !permission.settled && permission.request.sessionId === sessionId)) return;
1124
+ const proof = await local.readCleanSessionProof!(state.storageKey, sessionId);
1125
+ if (!proof || flexSessionDigest(proof.session) !== flexSessionDigest(stored.session)) return;
1126
+ const [projection, agentEvents, existing] = await Promise.all([
1127
+ projections.loadHead!(state.storageKey, sessionId),
1128
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1129
+ projections.loadAuxiliarySummaryHead!(
1130
+ state.storageKey, sessionId, this.reversionPolicy === 'workspace-required',
1131
+ ),
1132
+ ]);
1133
+ const matches = (actual: { incarnationId?: string; revision: number; contentRoot: string } | undefined,
1134
+ expected: { incarnationId: string; revision: number; contentRoot: string }) =>
1135
+ actual?.incarnationId === expected.incarnationId
1136
+ && actual.revision === expected.revision
1137
+ && actual.contentRoot === expected.contentRoot;
1138
+ if (!matches(projection, proof.clean.projection)
1139
+ || !matches(agentEvents, proof.clean.agentEvents)
1140
+ || (existing && matches(existing.projection, proof.clean.projection))) return;
1141
+ const presentation = deriveReversionPresentation(stored.reversionSegments, this.reversionPolicy);
1142
+ if (!presentation) throw new FlexHarnessStoreFormatError('Settled reversion presentation exceeds its bounds.');
1143
+ await projections.saveAuxiliarySummaryHead!(
1144
+ state.storageKey, sessionId, projection!, this.reversionPolicy === 'workspace-required',
1145
+ { reversionPresentation: presentation, sessionMetrics: sessionMetricsView(stored.metrics) },
1146
+ );
1147
+ });
1148
+ }
1149
+
988
1150
  /** Settle a fully repaired session after its producers and pending effects have drained. */
989
1151
  public async settleQuiescentSessionRecovery(state: IStorageState, sessionId: string): Promise<void> {
990
1152
  const local = this.stores.scopes.sessionLocal;
@@ -1029,6 +1191,24 @@ export class FlexHarnessCore<TScope> {
1029
1191
  this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1030
1192
  ]);
1031
1193
  if (!projection?.incarnationId || !agentEvents?.incarnationId) return;
1194
+ if (this.stores.projections.saveAuxiliarySummaryHead) {
1195
+ const presentation = deriveReversionPresentation(stored.reversionSegments, this.reversionPolicy);
1196
+ if (!presentation) throw new FlexHarnessStoreFormatError('Settled reversion presentation exceeds its bounds.');
1197
+ await this.stores.projections.saveAuxiliarySummaryHead(
1198
+ state.storageKey, sessionId, projection, this.reversionPolicy === 'workspace-required',
1199
+ { reversionPresentation: presentation, sessionMetrics: sessionMetricsView(stored.metrics) },
1200
+ );
1201
+ const [currentProjection, currentAgentEvents] = await Promise.all([
1202
+ this.stores.projections.loadHead!(state.storageKey, sessionId),
1203
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1204
+ ]);
1205
+ if (currentProjection?.incarnationId !== projection.incarnationId
1206
+ || currentProjection.revision !== projection.revision
1207
+ || currentProjection.contentRoot !== projection.contentRoot
1208
+ || currentAgentEvents?.incarnationId !== agentEvents.incarnationId
1209
+ || currentAgentEvents.revision !== agentEvents.revision
1210
+ || currentAgentEvents.contentRoot !== agentEvents.contentRoot) return;
1211
+ }
1032
1212
  await local.publishSessionClean!(state.storageKey, catalogue.recoveryRevision, {
1033
1213
  sessionId,
1034
1214
  state: 'clean',
@@ -4,6 +4,7 @@ import {
4
4
  FlexHarnessSessionBusyError,
5
5
  FlexHarnessSlashCommandReentryError,
6
6
  FlexHarnessSlashCommandUnavailableError,
7
+ FlexHarnessStoreFormatError,
7
8
  FlexHarnessValidationError,
8
9
  } from './errors.js';
9
10
  import {
@@ -11,7 +12,6 @@ import {
11
12
  FLEX_REVERSION_REASON_CODE_MAX_BYTES,
12
13
  FLEX_REVERSION_REFERENCE_MAX_BYTES,
13
14
  FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
14
- FLEX_SESSION_REVERSION_BARRIER_CAUSES,
15
15
  FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
16
16
  type IFlexAgentContextInvocation,
17
17
  type IFlexAffectedWorkspace,
@@ -20,18 +20,18 @@ import {
20
20
  type IFlexPendingReversionRelease,
21
21
  type IFlexRedoSessionResult,
22
22
  type IFlexSessionGeneration,
23
- type IFlexSessionReversionGroup,
24
23
  type IFlexSessionReversionInfo,
24
+ type IFlexSessionReversionPresentation,
25
25
  type IFlexSessionTombstone,
26
26
  type IFlexUndoSessionResult,
27
27
  type TFlexProjectionSnapshot,
28
- type TFlexSessionReversionBarrierCause,
29
28
  type TFlexTurnReversionFinalizedOutcome,
30
29
  type TJsonValue,
31
30
  } from './interfaces.js';
32
31
  import { cloneSerializable, normalizeJsonValue } from './utils.json.js';
33
32
  import { createWholeProjectionChange } from './utils.projectionchange.js';
34
33
  import { publicSnapshot } from './utils.transfer.js';
34
+ import { deriveReversionGroups, deriveReversionPresentation, presentReversionGroups } from './utils.reversionpresentation.js';
35
35
  import type {
36
36
  TCanonicalOutcome,
37
37
  IStoredSessionState,
@@ -52,6 +52,20 @@ import type { FlexHarnessCore } from './classes.flexharness.core.js';
52
52
  export class FlexHarnessReversions<TScope> {
53
53
  constructor(private readonly core: FlexHarnessCore<TScope>) {}
54
54
 
55
+ public async getSessionReversionPresentation(
56
+ scopeId: string,
57
+ sessionId: string,
58
+ signal?: AbortSignal,
59
+ ): Promise<IFlexSessionReversionPresentation> {
60
+ const source = await this.core.readSessionAuxiliarySource(scopeId, sessionId, signal);
61
+ if (source.summary) return publicSnapshot(source.summary.reversionPresentation);
62
+ const presentation = deriveReversionPresentation(
63
+ source.stored.reversionSegments, this.core.reversionPolicy,
64
+ );
65
+ if (!presentation) throw new FlexHarnessStoreFormatError('Session reversion presentation exceeds its bounds.');
66
+ return publicSnapshot(presentation);
67
+ }
68
+
55
69
  public async getSessionReversionInfo(
56
70
  scopeId: string,
57
71
  sessionId: string,
@@ -77,15 +91,7 @@ export class FlexHarnessReversions<TScope> {
77
91
  return publicSnapshot({
78
92
  undoAvailable: isAvailable(undo),
79
93
  redoAvailable: isAvailable(redo),
80
- groups: groups.map((group, index): IFlexSessionReversionGroup => ({
81
- runId: group.target.runId,
82
- kind: group.kind,
83
- visibility: index < stored.revertCursor ? 'visible' : 'hidden',
84
- affectedWorkspaces: cloneSerializable(group.affectedWorkspaces),
85
- affectedWorkspacesTruncated: group.affectedWorkspacesTruncated,
86
- barrierCauses: [...group.barrierCauses],
87
- reasonCodes: [...group.reasonCodes],
88
- })),
94
+ groups: presentReversionGroups(groups, stored.revertCursor),
89
95
  });
90
96
  }
91
97
 
@@ -135,63 +141,7 @@ export class FlexHarnessReversions<TScope> {
135
141
  }
136
142
 
137
143
  public reversionGroups(stored: IStoredSessionState): IReversionGroup[] {
138
- const groups: IReversionGroup[] = [];
139
- let leading: IFlexReversionSegment[] = [];
140
- for (const segment of stored.reversionSegments) {
141
- if (segment.status === 'completed') {
142
- const segments = groups.length === 0 ? [...leading, segment] : [segment];
143
- leading = [];
144
- groups.push({
145
- target: segment,
146
- segments,
147
- kind: 'candidate',
148
- affectedWorkspaces: [],
149
- affectedWorkspacesTruncated: false,
150
- barrierCauses: [],
151
- reasonCodes: [],
152
- });
153
- } else if (groups.length > 0) {
154
- groups[groups.length - 1].segments.push(segment);
155
- } else {
156
- leading.push(segment);
157
- }
158
- }
159
- for (const group of groups) {
160
- const affected = new Map<string, IFlexAffectedWorkspace>();
161
- for (const workspace of group.segments.flatMap((segment) =>
162
- segment.affectedWorkspaces ?? [])) {
163
- if (affected.has(workspace.id)) continue;
164
- if (affected.size < FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
165
- affected.set(workspace.id, cloneSerializable(workspace));
166
- } else {
167
- group.affectedWorkspacesTruncated = true;
168
- }
169
- }
170
- group.affectedWorkspaces = [...affected.values()];
171
- group.reasonCodes = [...new Set(group.segments.flatMap((segment) => (
172
- segment.disposition === 'nonrevertible' && segment.reasonCode !== undefined
173
- ? [segment.reasonCode]
174
- : []
175
- )))];
176
- if (this.core.reversionPolicy === 'transcript-optional') continue;
177
- const causes = new Set<TFlexSessionReversionBarrierCause>();
178
- for (const segment of group.segments) {
179
- if (segment.status === 'capturing' || segment.disposition === 'pending') causes.add('pending');
180
- if (segment.disposition === 'nonrevertible') causes.add('nonrevertible');
181
- if (segment.protocolVersion === 1 && segment.provenance === 'transcript') {
182
- causes.add('transcript-only');
183
- }
184
- }
185
- if (causes.size > 0) {
186
- group.kind = 'barrier';
187
- group.barrierCauses = FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => causes.has(cause));
188
- } else if (group.segments.some((segment) => segment.disposition === 'revertible')) {
189
- group.kind = 'candidate';
190
- } else {
191
- group.kind = 'no-change';
192
- }
193
- }
194
- return groups;
144
+ return deriveReversionGroups(stored.reversionSegments, this.core.reversionPolicy);
195
145
  }
196
146
 
197
147
  private async requireReversionIdle(
@@ -340,10 +340,9 @@ export class FlexHarnessSessions<TScope> {
340
340
  }
341
341
 
342
342
  public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
343
- const { state } = await this.core.resolveState(scopeId, sessionId);
344
- const stored = this.core.requireSession(state, sessionId);
345
- await stored.projectionQueue;
346
- this.core.assertStateAcceptingWork(state);
343
+ const source = await this.core.readSessionAuxiliarySource(scopeId, sessionId);
344
+ if (source.summary) return publicSnapshot(source.summary.sessionMetrics);
345
+ const stored = source.stored;
347
346
  if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
348
347
  return publicSnapshot(sessionMetricsView(stored.metrics));
349
348
  }
@@ -41,6 +41,7 @@ import type {
41
41
  IFlexSessionImportHandle,
42
42
  IFlexSessionImportProgress,
43
43
  IFlexSessionReversionInfo,
44
+ IFlexSessionReversionPresentation,
44
45
  IFlexSlashCommandDescriptor,
45
46
  IFlexSlashCommandExecutionOptions,
46
47
  IFlexUncertainToolExecution,
@@ -155,6 +156,15 @@ export class FlexHarness<TScope = unknown> {
155
156
  return this.core.reversions.getSessionReversionInfo(scopeId, sessionId);
156
157
  }
157
158
 
159
+ /** Bounded Git reversion summary, read from a clean projection head when available. */
160
+ public getSessionReversionPresentation(
161
+ scopeId: string,
162
+ sessionId: string,
163
+ signal?: AbortSignal,
164
+ ): Promise<IFlexSessionReversionPresentation> {
165
+ return this.core.reversions.getSessionReversionPresentation(scopeId, sessionId, signal);
166
+ }
167
+
158
168
  public updateSession(
159
169
  scopeId: string,
160
170
  sessionId: string,
package/ts/index.ts CHANGED
@@ -47,6 +47,10 @@ export {
47
47
  type TFlexProjectionIndexNode,
48
48
  } from './utils.projectionindex.js';
49
49
  export { assertFlexToolJobSnapshot } from './utils.storecodecs.js';
50
+ export {
51
+ assertFlexSessionAuxiliarySummary,
52
+ assertFlexSessionReversionPresentation,
53
+ } from './utils.reversionpresentation.js';
50
54
  export {
51
55
  FLEX_SLASH_COMMAND_MAX_INPUT_BYTES,
52
56
  isReservedSlashCommandName,
package/ts/interfaces.ts CHANGED
@@ -1878,6 +1878,23 @@ export interface IFlexProjectionStore {
1878
1878
  load(storageKey: string, sessionId: string): Promise<TFlexProjectionSnapshot | undefined>;
1879
1879
  /** Optional bounded content commitment; undefined requires a full load. */
1880
1880
  loadHead?(storageKey: string, sessionId: string): Promise<IFlexProjectionHead | undefined>;
1881
+ /** Optional bounded summary bound to the exact rooted projection head and grouping-policy flag. */
1882
+ loadAuxiliarySummaryHead?(
1883
+ storageKey: string,
1884
+ sessionId: string,
1885
+ workspaceRequired: boolean,
1886
+ ): Promise<{
1887
+ projection: IFlexProjectionHead;
1888
+ summary: IFlexSessionAuxiliarySummary;
1889
+ } | undefined>;
1890
+ /** Stores a summary bound to this exact head; one current slot per session and flag is valid. */
1891
+ saveAuxiliarySummaryHead?(
1892
+ storageKey: string,
1893
+ sessionId: string,
1894
+ expectedProjection: IFlexProjectionHead,
1895
+ workspaceRequired: boolean,
1896
+ summary: IFlexSessionAuxiliarySummary,
1897
+ ): Promise<void>;
1881
1898
  /**
1882
1899
  * Applies `change` to the stored projection while its revision is `expectedRevision`; the
1883
1900
  * change's revision is the next one.
@@ -2147,6 +2164,21 @@ export interface IFlexSessionReversionInfo {
2147
2164
  readonly groups: readonly IFlexSessionReversionGroup[];
2148
2165
  }
2149
2166
 
2167
+ /** Bounded, group-ordered summary for a session's reversion presentation. */
2168
+ export interface IFlexSessionReversionPresentation {
2169
+ readonly affectedWorkspaces: readonly IFlexAffectedWorkspace[];
2170
+ readonly affectedWorkspacesTruncated: boolean;
2171
+ readonly barrierCauses: readonly TFlexSessionReversionBarrierCause[];
2172
+ readonly reasonCodes: readonly string[];
2173
+ readonly reasonCodesTruncated: boolean;
2174
+ }
2175
+
2176
+ /** A settled session's bounded auxiliary view, tied to one exact committed projection head. */
2177
+ export interface IFlexSessionAuxiliarySummary {
2178
+ readonly reversionPresentation: IFlexSessionReversionPresentation;
2179
+ readonly sessionMetrics: IFlexSessionMetrics;
2180
+ }
2181
+
2150
2182
  export interface IFlexUndoSessionResult {
2151
2183
  revertedRunId: string;
2152
2184
  }
package/ts/readme.md CHANGED
@@ -699,6 +699,8 @@ await harness.reconcileToolExecution(scopeId, sessionId, intentId, {
699
699
  });
700
700
  const reversion = await harness.getSessionReversionInfo(scopeId, sessionId);
701
701
  console.log(reversion.undoAvailable, reversion.redoAvailable, reversion.groups);
702
+ const reversionPresentation = await harness.getSessionReversionPresentation(scopeId, sessionId);
703
+ console.log(reversionPresentation.affectedWorkspaces, reversionPresentation.barrierCauses);
702
704
  const undone = await harness.undoSession(scopeId, sessionId);
703
705
  console.log(undone.revertedRunId);
704
706
  const redone = await harness.redoSession(scopeId, sessionId);
@@ -1057,6 +1059,8 @@ for (const group of info.groups) {
1057
1059
 
1058
1060
  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. `barrierCauses` states why a barrier blocks traversal, each cause once in this order: `pending` while a capture runs or its outcome is not final, `nonrevertible` for a workspace outcome that cannot be reverted, `transcript-only` for legacy transcript history without a workspace capture; it is empty for candidate and no-change groups (`FLEX_SESSION_REVERSION_BARRIER_CAUSES` lists the order). `reasonCodes` lists the distinct `reasonCode`s of the group's nonrevertible segments in segment order, so an application can say why a turn is not revertible even when its provider named no affected workspace. It never includes capture IDs or provider references.
1059
1061
 
1062
+ `getSessionReversionPresentation(scopeId, sessionId, signal?)` returns one immutable bounded union for a Git reversion strip without per-turn groups or undo/redo availability. It keeps the first 64 distinct affected workspaces and first 64 distinct nonrevertible reason codes in historical group order, with separate `affectedWorkspacesTruncated` and `reasonCodesTruncated` flags. `barrierCauses` uses the same policy and fixed order as the full group view. A settled clean session can serve this view and `getSessionMetrics()` from one optional auxiliary summary bound to the exact rooted projection head and policy flag; the guarded read also checks the clean sidecar and Agent-event head through completion. Missing or stale summaries hydrate only that session, repair it, and backfill the current summary. Custom stores without the summary capability retain the same hydrated results. The NoSQL store keeps one summary slot per session and policy, separate from the projection head, so older readers' strict head schema is unchanged.
1063
+
1060
1064
  `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.
1061
1065
 
1062
1066
  The protocol is durable and inspectable: