@modelprofile.com/flexharness 18.9.0 → 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 +15 -3
- package/dist_ts/classes.flexharness.core.js +211 -18
- package/dist_ts/classes.flexharness.d.ts +3 -1
- package/dist_ts/classes.flexharness.js +5 -1
- package/dist_ts/classes.flexharness.lifecycle.js +4 -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 +9 -6
- package/dist_ts/classes.recoverygate.d.ts +1 -0
- package/dist_ts/classes.recoverygate.js +4 -1
- 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 +5 -1
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +239 -36
- package/ts/classes.flexharness.lifecycle.ts +3 -0
- package/ts/classes.flexharness.reversions.ts +19 -69
- package/ts/classes.flexharness.sessions.ts +6 -5
- package/ts/classes.flexharness.ts +10 -0
- package/ts/classes.recoverygate.ts +4 -0
- package/ts/index.ts +4 -0
- package/ts/interfaces.ts +32 -0
- package/ts/readme.md +5 -1
- 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,
|
|
@@ -516,7 +519,7 @@ export class FlexHarnessCore<TScope> {
|
|
|
516
519
|
catalogue: new Map(liveScopeSessions(snapshot).map((session) => [session.sessionId, session])),
|
|
517
520
|
sessionLocal: local !== undefined,
|
|
518
521
|
qualifyingLegacy,
|
|
519
|
-
recoverySessionIds: new Set(local && local.recoverySchemaVersion
|
|
522
|
+
recoverySessionIds: new Set(local && local.recoverySchemaVersion === 2
|
|
520
523
|
&& !this.cleanRecoveryEnabled(storageKey)
|
|
521
524
|
? [...new Set([...local.recoverySessionIds,
|
|
522
525
|
...(local.snapshot?.sessions.map((session) => session.sessionId) ?? [])])]
|
|
@@ -557,6 +560,10 @@ export class FlexHarnessCore<TScope> {
|
|
|
557
560
|
for (const metadata of liveScopeSessions(snapshot).filter((session) =>
|
|
558
561
|
!state.sessionLocal || qualifyingLegacy || state.recoverySessionIds.has(session.sessionId))) {
|
|
559
562
|
compactorLifecycleController.signal.throwIfAborted();
|
|
563
|
+
if (local?.recoverySchemaVersion === 2 && !this.cleanRecoveryEnabled(storageKey)) {
|
|
564
|
+
// A compatibility open always invalidates inherited clean proof before full repair.
|
|
565
|
+
await this.markRecoveryRequired(state, metadata.sessionId);
|
|
566
|
+
}
|
|
560
567
|
const stored = await this.loadSessionRuntime(
|
|
561
568
|
state,
|
|
562
569
|
metadata,
|
|
@@ -655,7 +662,7 @@ export class FlexHarnessCore<TScope> {
|
|
|
655
662
|
for (const loaded of loadedSessions) {
|
|
656
663
|
loaded.recovering = false;
|
|
657
664
|
await this.updateRecoveryObligation(state, loaded);
|
|
658
|
-
await this.
|
|
665
|
+
await this.settleQuiescentSessionRecovery(state, loaded.session.sessionId);
|
|
659
666
|
}
|
|
660
667
|
}
|
|
661
668
|
return state;
|
|
@@ -786,7 +793,7 @@ export class FlexHarnessCore<TScope> {
|
|
|
786
793
|
else state.catalogue.set(sessionId, stored.session);
|
|
787
794
|
stored.recovering = false;
|
|
788
795
|
await this.updateRecoveryObligation(state, stored);
|
|
789
|
-
await this.
|
|
796
|
+
await this.settleQuiescentSessionRecovery(state, sessionId);
|
|
790
797
|
this.assertStateAcceptingWork(state);
|
|
791
798
|
return stored;
|
|
792
799
|
} catch (error) {
|
|
@@ -827,6 +834,8 @@ export class FlexHarnessCore<TScope> {
|
|
|
827
834
|
if (state.sessionLoads.has(id)) { await state.sessionLoads.get(id); continue; }
|
|
828
835
|
const stored = state.sessions.get(id);
|
|
829
836
|
if (!stored) { await this.hydrateSession(state, id, scopeId, scope); continue; }
|
|
837
|
+
await this.settleQuiescentSessionRecovery(state, id);
|
|
838
|
+
if (!state.recoverySessionIds.has(id)) continue;
|
|
830
839
|
stored.recovering = true;
|
|
831
840
|
await this.repairLoadedSession(state.storageKey, stored, state, scopeId, scope,
|
|
832
841
|
new FlexTimeSlicer(state.compactorLifecycleController.signal));
|
|
@@ -835,6 +844,7 @@ export class FlexHarnessCore<TScope> {
|
|
|
835
844
|
await this.mutateSessionScope(state, id, () => undefined);
|
|
836
845
|
stored.recovering = false;
|
|
837
846
|
await this.updateRecoveryObligation(state, stored);
|
|
847
|
+
await this.settleQuiescentSessionRecovery(state, id);
|
|
838
848
|
}
|
|
839
849
|
for (const root of roots) await this.deletion.finishTombstoneCleanup(state, root, scopeId, { scopeId, scope });
|
|
840
850
|
})().finally(() => { if (state.sharedRecovery === recovery) delete state.sharedRecovery; });
|
|
@@ -879,10 +889,10 @@ export class FlexHarnessCore<TScope> {
|
|
|
879
889
|
private recoveryProducerGate(state: IStorageState, sessionId: string): FlexRecoveryProducerGate {
|
|
880
890
|
let gate = state.recoveryProducerGates.get(sessionId);
|
|
881
891
|
if (!gate) {
|
|
882
|
-
gate = new FlexRecoveryProducerGate(
|
|
883
|
-
void this.
|
|
892
|
+
gate = new FlexRecoveryProducerGate(() => {
|
|
893
|
+
void this.settleQuiescentSessionRecovery(state, sessionId)
|
|
884
894
|
.catch((error: unknown) => this.lifecycle.deferNamespaceDrain(state, error));
|
|
885
|
-
}
|
|
895
|
+
});
|
|
886
896
|
state.recoveryProducerGates.set(sessionId, gate);
|
|
887
897
|
}
|
|
888
898
|
return gate;
|
|
@@ -978,20 +988,132 @@ export class FlexHarnessCore<TScope> {
|
|
|
978
988
|
});
|
|
979
989
|
}
|
|
980
990
|
|
|
981
|
-
/**
|
|
982
|
-
public
|
|
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> {
|
|
983
996
|
const local = this.stores.scopes.sessionLocal;
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|| !
|
|
987
|
-
|
|
988
|
-
|
|
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;
|
|
989
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;
|
|
990
1113
|
await this.withRecoveryPublication(state, sessionId, async () => {
|
|
991
1114
|
const stored = state.sessions.get(sessionId);
|
|
992
|
-
if (!stored ||
|
|
993
|
-
|| stored.
|
|
994
|
-
|| state.initializingSessions.has(sessionId)
|
|
1115
|
+
if (!stored || stored.recovering || stored.projectionReconciliationRequired
|
|
1116
|
+
|| stored.metricsFailure !== undefined || state.initializingSessions.has(sessionId)
|
|
995
1117
|
|| state.tombstones.has(sessionId) || state.activeRuns.has(sessionId)
|
|
996
1118
|
|| stored.outstandingPromptsById.size > 0 || stored.pendingReversion !== undefined
|
|
997
1119
|
|| stored.pendingReversionReleases.length > 0 || stored.stagedTerminals.length > 0
|
|
@@ -999,27 +1121,107 @@ export class FlexHarnessCore<TScope> {
|
|
|
999
1121
|
|| stored.metrics.pendingCompactionId !== undefined
|
|
1000
1122
|
|| [...state.pendingPermissions.values()].some((permission) =>
|
|
1001
1123
|
!permission.settled && permission.request.sessionId === sessionId)) return;
|
|
1002
|
-
const
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
const [projection, agentEvents] = await Promise.all([
|
|
1007
|
-
this.stores.projections.loadHead!(state.storageKey, sessionId),
|
|
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),
|
|
1008
1128
|
this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
|
|
1129
|
+
projections.loadAuxiliarySummaryHead!(
|
|
1130
|
+
state.storageKey, sessionId, this.reversionPolicy === 'workspace-required',
|
|
1131
|
+
),
|
|
1009
1132
|
]);
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
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
|
+
);
|
|
1022
1147
|
});
|
|
1148
|
+
}
|
|
1149
|
+
|
|
1150
|
+
/** Settle a fully repaired session after its producers and pending effects have drained. */
|
|
1151
|
+
public async settleQuiescentSessionRecovery(state: IStorageState, sessionId: string): Promise<void> {
|
|
1152
|
+
const local = this.stores.scopes.sessionLocal;
|
|
1153
|
+
if (!state.sessionLocal || state.qualifyingLegacy || state.lifecycle !== 'active'
|
|
1154
|
+
|| !local || !state.recoverySessionIds.has(sessionId)) return;
|
|
1155
|
+
const cleanRead = this.cleanRecoveryEnabled(state.storageKey);
|
|
1156
|
+
if (cleanRead && (!local.publishSessionClean || !this.stores.projections.loadHead
|
|
1157
|
+
|| !this.stores.agentEvents.loadHead)) return;
|
|
1158
|
+
const gate = this.recoveryProducerGate(state, sessionId);
|
|
1159
|
+
if (!gate.canPublish) return;
|
|
1160
|
+
try {
|
|
1161
|
+
await gate.publish(async () => {
|
|
1162
|
+
const stored = state.sessions.get(sessionId);
|
|
1163
|
+
if (!stored || state.lifecycle !== 'active' || state.qualifyingLegacy || stored.recovering
|
|
1164
|
+
|| !state.recoverySessionIds.has(sessionId)
|
|
1165
|
+
|| stored.projectionReconciliationRequired || stored.metricsFailure !== undefined
|
|
1166
|
+
|| state.initializingSessions.has(sessionId)
|
|
1167
|
+
|| state.tombstones.has(sessionId) || state.activeRuns.has(sessionId)
|
|
1168
|
+
|| stored.outstandingPromptsById.size > 0 || stored.pendingReversion !== undefined
|
|
1169
|
+
|| stored.pendingReversionReleases.length > 0 || stored.stagedTerminals.length > 0
|
|
1170
|
+
|| stored.metrics.pendingGenerationId !== undefined
|
|
1171
|
+
|| stored.metrics.pendingCompactionId !== undefined
|
|
1172
|
+
|| [...state.pendingPermissions.values()].some((permission) =>
|
|
1173
|
+
!permission.settled && permission.request.sessionId === sessionId)) return;
|
|
1174
|
+
const catalogue = await local.loadCatalogue(state.storageKey);
|
|
1175
|
+
const session = catalogue.snapshot?.sessions.find((entry) => entry.sessionId === sessionId);
|
|
1176
|
+
if (!catalogue.qualified || !session
|
|
1177
|
+
|| flexSessionDigest(session) !== flexSessionDigest(stored.session)) return;
|
|
1178
|
+
if (!cleanRead) {
|
|
1179
|
+
// Compatibility has recovered this runtime. Schema 2 still requires full recovery
|
|
1180
|
+
// in the next runtime, since this mode does not publish authenticated clean proof.
|
|
1181
|
+
if (catalogue.recoverySchemaVersion !== 2) {
|
|
1182
|
+
await local.setRecoveryRequired(state.storageKey, sessionId, false);
|
|
1183
|
+
}
|
|
1184
|
+
state.recoverySessionIds.delete(sessionId);
|
|
1185
|
+
state.recoveryMarks.delete(sessionId);
|
|
1186
|
+
return;
|
|
1187
|
+
}
|
|
1188
|
+
if (catalogue.recoveryRevision === undefined) return;
|
|
1189
|
+
const [projection, agentEvents] = await Promise.all([
|
|
1190
|
+
this.stores.projections.loadHead!(state.storageKey, sessionId),
|
|
1191
|
+
this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
|
|
1192
|
+
]);
|
|
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
|
+
}
|
|
1212
|
+
await local.publishSessionClean!(state.storageKey, catalogue.recoveryRevision, {
|
|
1213
|
+
sessionId,
|
|
1214
|
+
state: 'clean',
|
|
1215
|
+
...requireSessionGeneration(session),
|
|
1216
|
+
sessionDigest: flexSessionDigest(session),
|
|
1217
|
+
projection: { incarnationId: projection.incarnationId, revision: projection.revision,
|
|
1218
|
+
contentRoot: projection.contentRoot },
|
|
1219
|
+
agentEvents: { incarnationId: agentEvents.incarnationId, revision: agentEvents.revision,
|
|
1220
|
+
contentRoot: agentEvents.contentRoot },
|
|
1221
|
+
});
|
|
1222
|
+
state.recoverySessionIds.delete(sessionId);
|
|
1223
|
+
state.recoveryMarks.delete(sessionId);
|
|
1224
|
+
});
|
|
1023
1225
|
} catch (error) {
|
|
1024
1226
|
// Another session can advance the namespace sidecar between our read and exact CAS.
|
|
1025
1227
|
// This session remains durably dirty and another settled read can publish it.
|
|
@@ -1049,8 +1251,8 @@ export class FlexHarnessCore<TScope> {
|
|
|
1049
1251
|
else if (!registerOnly) state.recoverySessionIds.delete(sessionId);
|
|
1050
1252
|
return;
|
|
1051
1253
|
}
|
|
1052
|
-
//
|
|
1053
|
-
//
|
|
1254
|
+
// The quiescent settlement path clears marks after the event, job, permission and metadata
|
|
1255
|
+
// writers have settled.
|
|
1054
1256
|
if (!required) return;
|
|
1055
1257
|
await this.markRecoveryRequired(state, sessionId);
|
|
1056
1258
|
}
|
|
@@ -1065,6 +1267,7 @@ export class FlexHarnessCore<TScope> {
|
|
|
1065
1267
|
if (!state.sessionLocal || state.lifecycle !== 'active') return;
|
|
1066
1268
|
try {
|
|
1067
1269
|
await this.updateRecoveryObligation(state, stored);
|
|
1270
|
+
await this.settleQuiescentSessionRecovery(state, stored.session.sessionId);
|
|
1068
1271
|
} catch (error) {
|
|
1069
1272
|
this.lifecycle.deferNamespaceDrain(state, error);
|
|
1070
1273
|
}
|
|
@@ -722,6 +722,9 @@ export class FlexHarnessLifecycle<TScope> {
|
|
|
722
722
|
this.core.appendUnexpectedErrors(errors, error);
|
|
723
723
|
}
|
|
724
724
|
}
|
|
725
|
+
// Retirement has closed publication admission. Join the sidecar write before releasing
|
|
726
|
+
// the storage key so a new runtime cannot race a late recovery update.
|
|
727
|
+
await Promise.all([...state.recoveryProducerGates.values()].map((gate) => gate.waitForPublication()));
|
|
725
728
|
errors.push(...state.fenceAdditionalErrors.splice(0));
|
|
726
729
|
if (errors.length > 0) throw combineErrors(errors);
|
|
727
730
|
state.lifecycle = 'retired';
|
|
@@ -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(
|
|
@@ -289,6 +289,8 @@ export class FlexHarnessSessions<TScope> {
|
|
|
289
289
|
resolved.state.initializingSessions.delete(sessionId);
|
|
290
290
|
completeInitialization();
|
|
291
291
|
}
|
|
292
|
+
const stored = resolved.state.sessions.get(sessionId);
|
|
293
|
+
if (stored) await this.core.settleRecoveryObligation(resolved.state, stored);
|
|
292
294
|
const result = publicSnapshot(metadata);
|
|
293
295
|
this.core.emitEvent(scopeId, metadata, { type: 'session.created', session: result });
|
|
294
296
|
return result;
|
|
@@ -330,7 +332,7 @@ export class FlexHarnessSessions<TScope> {
|
|
|
330
332
|
await (aborted ? Promise.race([hydration, aborted]) : hydration);
|
|
331
333
|
throwIfAborted();
|
|
332
334
|
}
|
|
333
|
-
await this.core.
|
|
335
|
+
await this.core.settleQuiescentSessionRecovery(state, sessionId);
|
|
334
336
|
return publicSnapshot(this.core.requireSession(state, sessionId).session);
|
|
335
337
|
} finally {
|
|
336
338
|
if (signal && onAbort) signal.removeEventListener('abort', onAbort);
|
|
@@ -338,10 +340,9 @@ export class FlexHarnessSessions<TScope> {
|
|
|
338
340
|
}
|
|
339
341
|
|
|
340
342
|
public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
|
|
341
|
-
const
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
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;
|
|
345
346
|
if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
|
|
346
347
|
return publicSnapshot(sessionMetricsView(stored.metrics));
|
|
347
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,
|
|
@@ -25,6 +25,10 @@ export class FlexRecoveryProducerGate {
|
|
|
25
25
|
&& this.runs === 0 && !this.runFailed;
|
|
26
26
|
}
|
|
27
27
|
|
|
28
|
+
public async waitForPublication(): Promise<void> {
|
|
29
|
+
await this.publication;
|
|
30
|
+
}
|
|
31
|
+
|
|
28
32
|
/** Generation execution may continue tool effects after prompt promotion has returned. */
|
|
29
33
|
public admitRun(completion: Promise<unknown>): void {
|
|
30
34
|
if (!this.context.getStore()?.leases) {
|
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
|
}
|