@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.
- package/dist_ts/00_commitinfo_data.js +2 -2
- package/dist_ts/classes.flexharness.core.d.ts +13 -1
- package/dist_ts/classes.flexharness.core.js +169 -2
- package/dist_ts/classes.flexharness.d.ts +3 -1
- package/dist_ts/classes.flexharness.js +5 -1
- package/dist_ts/classes.flexharness.reversions.d.ts +2 -1
- package/dist_ts/classes.flexharness.reversions.js +15 -75
- package/dist_ts/classes.flexharness.sessions.js +5 -5
- package/dist_ts/index.d.ts +1 -0
- package/dist_ts/index.js +2 -1
- package/dist_ts/interfaces.d.ts +20 -0
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/utils.reversionpresentation.d.ts +12 -0
- package/dist_ts/utils.reversionpresentation.js +219 -0
- package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +76 -4
- package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +1 -1
- package/dist_ts_stores_nosqldb/classes.recordstore.js +1 -1
- package/package.json +3 -3
- package/readme.md +4 -0
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +180 -0
- package/ts/classes.flexharness.reversions.ts +19 -69
- package/ts/classes.flexharness.sessions.ts +3 -4
- package/ts/classes.flexharness.ts +10 -0
- package/ts/index.ts +4 -0
- package/ts/interfaces.ts +32 -0
- package/ts/readme.md +4 -0
- package/ts/utils.reversionpresentation.ts +227 -0
- package/ts_stores_nosqldb/classes.nosqldbstores.ts +101 -2
- package/ts_stores_nosqldb/classes.recordstore.ts +1 -0
|
@@ -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
|
|
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
|
-
|
|
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
|
|
344
|
-
|
|
345
|
-
|
|
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:
|