@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.
@@ -0,0 +1,227 @@
1
+ import {
2
+ FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
3
+ FLEX_REVERSION_REASON_CODE_MAX_BYTES,
4
+ FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
5
+ FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
6
+ FLEX_SESSION_REVERSION_BARRIER_CAUSES,
7
+ type IFlexAffectedWorkspace,
8
+ type IFlexReversionSegment,
9
+ type IFlexSessionAuxiliarySummary,
10
+ type IFlexSessionMetricsState,
11
+ type IFlexSessionReversionGroup,
12
+ type IFlexSessionReversionPresentation,
13
+ type TFlexReversionPolicy,
14
+ type TFlexSessionReversionBarrierCause,
15
+ } from './interfaces.js';
16
+ import type { IReversionGroup } from './interfaces.flexharness.js';
17
+ import { FlexHarnessStoreFormatError } from './errors.js';
18
+ import { assertSessionMetrics, canonicalJson, cloneSerializable } from './utils.json.js';
19
+ import { sessionMetricsView } from './utils.sessionmetrics.js';
20
+
21
+ /** The aggregate has fixed limits regardless of the number of turns in a session. */
22
+ export const FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES = 64;
23
+ export const FLEX_REVERSION_PRESENTATION_MAX_BYTES = 256 * 1024;
24
+ export const FLEX_SESSION_AUXILIARY_SUMMARY_MAX_BYTES = FLEX_REVERSION_PRESENTATION_MAX_BYTES + 4096;
25
+
26
+ export function assertFlexSessionAuxiliarySummary(value: unknown): IFlexSessionAuxiliarySummary {
27
+ const invalid = () => new FlexHarnessStoreFormatError('Invalid session auxiliary summary.');
28
+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid();
29
+ const record = value as Record<string, unknown>;
30
+ if (JSON.stringify(Object.keys(record).sort()) !== JSON.stringify([
31
+ 'reversionPresentation', 'sessionMetrics',
32
+ ])) throw invalid();
33
+ assertFlexSessionReversionPresentation(record.reversionPresentation);
34
+ if (!record.sessionMetrics || typeof record.sessionMetrics !== 'object'
35
+ || Array.isArray(record.sessionMetrics)) throw invalid();
36
+ const metrics = record.sessionMetrics as Record<string, unknown>;
37
+ if (metrics.inFlight !== false) throw invalid();
38
+ const metricsState = { ...metrics };
39
+ delete metricsState.inFlight;
40
+ delete metricsState.lifetimeUsedTokens;
41
+ delete metricsState.lastObservedInputTokensFreshness;
42
+ assertSessionMetrics(metricsState);
43
+ if (canonicalJson(sessionMetricsView(metricsState as unknown as IFlexSessionMetricsState))
44
+ !== canonicalJson(metrics)) throw invalid();
45
+ if (Buffer.byteLength(JSON.stringify(value), 'utf8') > FLEX_SESSION_AUXILIARY_SUMMARY_MAX_BYTES) {
46
+ throw invalid();
47
+ }
48
+ return value as IFlexSessionAuxiliarySummary;
49
+ }
50
+
51
+ /** Checks an untrusted stored summary without opening its source projection. */
52
+ export function assertFlexSessionReversionPresentation(value: unknown): IFlexSessionReversionPresentation {
53
+ const invalid = () => new FlexHarnessStoreFormatError('Invalid session reversion presentation.');
54
+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid();
55
+ const record = value as Record<string, unknown>;
56
+ const keys = Object.keys(record).sort();
57
+ if (JSON.stringify(keys) !== JSON.stringify([
58
+ 'affectedWorkspaces', 'affectedWorkspacesTruncated', 'barrierCauses',
59
+ 'reasonCodes', 'reasonCodesTruncated',
60
+ ])) throw invalid();
61
+ if (!Array.isArray(record.affectedWorkspaces)
62
+ || record.affectedWorkspaces.length > FLEX_REVERSION_MAX_AFFECTED_WORKSPACES
63
+ || !Array.isArray(record.barrierCauses)
64
+ || !Array.isArray(record.reasonCodes)
65
+ || record.reasonCodes.length > FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES
66
+ || typeof record.affectedWorkspacesTruncated !== 'boolean'
67
+ || typeof record.reasonCodesTruncated !== 'boolean') throw invalid();
68
+ const workspaceIds = new Set<string>();
69
+ for (const workspace of record.affectedWorkspaces) {
70
+ if (!workspace || typeof workspace !== 'object' || Array.isArray(workspace)) throw invalid();
71
+ if (JSON.stringify(Object.keys(workspace).sort()) !== JSON.stringify(['id', 'label'])) throw invalid();
72
+ if (typeof workspace.id !== 'string' || !workspace.id.trim()
73
+ || typeof workspace.label !== 'string' || !workspace.label.trim()
74
+ || Buffer.byteLength(workspace.id, 'utf8') > FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES
75
+ || Buffer.byteLength(workspace.label, 'utf8') > FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES
76
+ || workspaceIds.has(workspace.id)) throw invalid();
77
+ workspaceIds.add(workspace.id);
78
+ }
79
+ const barrierCauses = record.barrierCauses;
80
+ if (JSON.stringify(barrierCauses) !== JSON.stringify(
81
+ FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => barrierCauses.includes(cause)),
82
+ )) throw invalid();
83
+ const reasonCodes = new Set<string>();
84
+ for (const reason of record.reasonCodes) {
85
+ if (typeof reason !== 'string'
86
+ || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(reason)
87
+ || Buffer.byteLength(reason, 'utf8') > FLEX_REVERSION_REASON_CODE_MAX_BYTES
88
+ || reasonCodes.has(reason)) throw invalid();
89
+ reasonCodes.add(reason);
90
+ }
91
+ if ((record.affectedWorkspacesTruncated && workspaceIds.size !== FLEX_REVERSION_MAX_AFFECTED_WORKSPACES)
92
+ || (record.reasonCodesTruncated && reasonCodes.size !== FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES)) {
93
+ throw invalid();
94
+ }
95
+ if (Buffer.byteLength(JSON.stringify(value), 'utf8') > FLEX_REVERSION_PRESENTATION_MAX_BYTES) {
96
+ throw invalid();
97
+ }
98
+ return value as IFlexSessionReversionPresentation;
99
+ }
100
+
101
+ export function deriveReversionGroups(
102
+ reversionSegments: readonly IFlexReversionSegment[],
103
+ reversionPolicy: TFlexReversionPolicy,
104
+ ): IReversionGroup[] {
105
+ const groups: IReversionGroup[] = [];
106
+ let leading: IFlexReversionSegment[] = [];
107
+ for (const segment of reversionSegments) {
108
+ if (segment.status === 'completed') {
109
+ const segments = groups.length === 0 ? [...leading, segment] : [segment];
110
+ leading = [];
111
+ groups.push({
112
+ target: segment,
113
+ segments,
114
+ kind: 'candidate',
115
+ affectedWorkspaces: [],
116
+ affectedWorkspacesTruncated: false,
117
+ barrierCauses: [],
118
+ reasonCodes: [],
119
+ });
120
+ } else if (groups.length > 0) {
121
+ groups[groups.length - 1].segments.push(segment);
122
+ } else {
123
+ leading.push(segment);
124
+ }
125
+ }
126
+ for (const group of groups) {
127
+ const affected = new Map<string, IFlexAffectedWorkspace>();
128
+ for (const workspace of group.segments.flatMap((segment) =>
129
+ segment.affectedWorkspaces ?? [])) {
130
+ if (affected.has(workspace.id)) continue;
131
+ if (affected.size < FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
132
+ affected.set(workspace.id, cloneSerializable(workspace));
133
+ } else {
134
+ group.affectedWorkspacesTruncated = true;
135
+ }
136
+ }
137
+ group.affectedWorkspaces = [...affected.values()];
138
+ group.reasonCodes = [...new Set(group.segments.flatMap((segment) => (
139
+ segment.disposition === 'nonrevertible' && segment.reasonCode !== undefined
140
+ ? [segment.reasonCode]
141
+ : []
142
+ )))];
143
+ if (reversionPolicy === 'transcript-optional') continue;
144
+ const causes = new Set<TFlexSessionReversionBarrierCause>();
145
+ for (const segment of group.segments) {
146
+ if (segment.status === 'capturing' || segment.disposition === 'pending') causes.add('pending');
147
+ if (segment.disposition === 'nonrevertible') causes.add('nonrevertible');
148
+ if (segment.protocolVersion === 1 && segment.provenance === 'transcript') {
149
+ causes.add('transcript-only');
150
+ }
151
+ }
152
+ if (causes.size > 0) {
153
+ group.kind = 'barrier';
154
+ group.barrierCauses = FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => causes.has(cause));
155
+ } else if (group.segments.some((segment) => segment.disposition === 'revertible')) {
156
+ group.kind = 'candidate';
157
+ } else {
158
+ group.kind = 'no-change';
159
+ }
160
+ }
161
+ return groups;
162
+ }
163
+
164
+ export function presentReversionGroups(
165
+ groups: readonly IReversionGroup[],
166
+ revertCursor: number,
167
+ ): IFlexSessionReversionGroup[] {
168
+ return groups.map((group, index): IFlexSessionReversionGroup => ({
169
+ runId: group.target.runId,
170
+ kind: group.kind,
171
+ visibility: index < revertCursor ? 'visible' : 'hidden',
172
+ affectedWorkspaces: cloneSerializable(group.affectedWorkspaces),
173
+ affectedWorkspacesTruncated: group.affectedWorkspacesTruncated,
174
+ barrierCauses: [...group.barrierCauses],
175
+ reasonCodes: [...group.reasonCodes],
176
+ }));
177
+ }
178
+
179
+ export function deriveReversionPresentation(
180
+ reversionSegments: readonly IFlexReversionSegment[],
181
+ reversionPolicy: TFlexReversionPolicy,
182
+ ): IFlexSessionReversionPresentation | undefined {
183
+ const affectedWorkspaces = new Map<string, IFlexAffectedWorkspace>();
184
+ const reasonCodes = new Set<string>();
185
+ const causes = new Set<TFlexSessionReversionBarrierCause>();
186
+ let affectedWorkspacesTruncated = false;
187
+ let reasonCodesTruncated = false;
188
+ for (const group of deriveReversionGroups(reversionSegments, reversionPolicy)) {
189
+ for (const segment of group.segments) {
190
+ for (const workspace of segment.affectedWorkspaces ?? []) {
191
+ if (
192
+ Buffer.byteLength(workspace.id, 'utf8') > FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES
193
+ || Buffer.byteLength(workspace.label, 'utf8') > FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES
194
+ ) return undefined;
195
+ if (affectedWorkspaces.has(workspace.id)) continue;
196
+ if (affectedWorkspaces.size >= FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
197
+ affectedWorkspacesTruncated = true;
198
+ } else {
199
+ affectedWorkspaces.set(workspace.id, cloneSerializable(workspace));
200
+ }
201
+ }
202
+ }
203
+ for (const cause of group.barrierCauses) causes.add(cause);
204
+ for (const reasonCode of group.reasonCodes) {
205
+ if (Buffer.byteLength(reasonCode, 'utf8') > FLEX_REVERSION_REASON_CODE_MAX_BYTES) {
206
+ return undefined;
207
+ }
208
+ if (reasonCodes.has(reasonCode)) continue;
209
+ if (reasonCodes.size >= FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES) {
210
+ reasonCodesTruncated = true;
211
+ } else {
212
+ reasonCodes.add(reasonCode);
213
+ }
214
+ }
215
+ }
216
+ const presentation: IFlexSessionReversionPresentation = {
217
+ affectedWorkspaces: [...affectedWorkspaces.values()],
218
+ affectedWorkspacesTruncated,
219
+ barrierCauses: FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => causes.has(cause)),
220
+ reasonCodes: [...reasonCodes],
221
+ reasonCodesTruncated,
222
+ };
223
+ if (Buffer.byteLength(JSON.stringify(presentation), 'utf8') > FLEX_REVERSION_PRESENTATION_MAX_BYTES) {
224
+ return undefined;
225
+ }
226
+ return presentation;
227
+ }
@@ -4,7 +4,7 @@ import {
4
4
  RecoverableFlexScopeStore,
5
5
  validateFlexScopeRecoverySave,
6
6
  } from '../ts/classes.scoperecovery.js';
7
- import { FlexHarnessStoreConflictError, FlexHarnessValidationError } from '../ts/errors.js';
7
+ import { FlexHarnessStoreConflictError, FlexHarnessStoreFormatError, FlexHarnessValidationError } from '../ts/errors.js';
8
8
  import type {
9
9
  IFlexAgentEventStoreProvider,
10
10
  IFlexHarnessStores,
@@ -15,7 +15,9 @@ import type {
15
15
  IFlexProjectManagementTombstone,
16
16
  IFlexProjectManagementWriteContext,
17
17
  IFlexProjectionChange,
18
+ IFlexProjectionHead,
18
19
  IFlexProjectionStore,
20
+ IFlexSessionAuxiliarySummary,
19
21
  IFlexResultStore,
20
22
  TFlexScopeRecoverySnapshot,
21
23
  IFlexScopeRecoveryStoreV2,
@@ -31,6 +33,7 @@ import {
31
33
  assertFlexProjectionSnapshot,
32
34
  assertFlexScopeSnapshot,
33
35
  assertJsonSerializable,
36
+ canonicalJson,
34
37
  } from '../ts/utils.json.js';
35
38
  import {
36
39
  assertFlexProjectManagementRecord,
@@ -42,6 +45,7 @@ import {
42
45
  assertFlexProjectionChange,
43
46
  validateProjectionChangeSave,
44
47
  } from '../ts/utils.projectionchange.js';
48
+ import { assertFlexSessionAuxiliarySummary } from '../ts/utils.reversionpresentation.js';
45
49
  import {
46
50
  assertFlexToolJobSnapshot,
47
51
  createChangedAgentEventSnapshot,
@@ -171,10 +175,105 @@ class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStoreV2 {
171
175
  }
172
176
  }
173
177
 
178
+ interface ISessionAuxiliarySummarySlot {
179
+ revision: number;
180
+ projection: IFlexProjectionHead;
181
+ summary: IFlexSessionAuxiliarySummary;
182
+ }
183
+
174
184
  /** A projection is a log record: a save writes its change, checked in form. */
175
185
  class NoSqlProjectionStore implements IFlexProjectionStore {
176
186
  constructor(private readonly records: FlexRecordStore) {}
177
187
 
188
+ private auxiliarySummaryAddress(
189
+ storageKey: string,
190
+ sessionId: string,
191
+ workspaceRequired: boolean,
192
+ ) {
193
+ return {
194
+ domain: 'sessionAuxiliarySummary' as const,
195
+ storageKey,
196
+ sessionId,
197
+ entryId: workspaceRequired ? 'workspace-required' : 'transcript-optional',
198
+ };
199
+ }
200
+
201
+ private assertAuxiliarySummarySlot(value: unknown): ISessionAuxiliarySummarySlot {
202
+ const invalid = () => new FlexHarnessStoreFormatError('Invalid auxiliary summary slot.');
203
+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid();
204
+ const slot = value as Record<string, unknown>;
205
+ if (JSON.stringify(Object.keys(slot).sort()) !== JSON.stringify(['projection', 'revision', 'summary'])
206
+ || !Number.isSafeInteger(slot.revision) || Number(slot.revision) < 1
207
+ || !slot.projection || typeof slot.projection !== 'object' || Array.isArray(slot.projection)) {
208
+ throw invalid();
209
+ }
210
+ const projection = slot.projection as Record<string, unknown>;
211
+ if (JSON.stringify(Object.keys(projection).sort())
212
+ !== JSON.stringify(['contentRoot', 'incarnationId', 'revision'])
213
+ || typeof projection.incarnationId !== 'string' || !projection.incarnationId
214
+ || typeof projection.contentRoot !== 'string' || !/^[a-f0-9]{64}$/u.test(projection.contentRoot)
215
+ || !Number.isSafeInteger(projection.revision) || Number(projection.revision) < 1) throw invalid();
216
+ assertFlexSessionAuxiliarySummary(slot.summary);
217
+ return value as ISessionAuxiliarySummarySlot;
218
+ }
219
+
220
+ private matchesProjection(left: IFlexProjectionHead, right: IFlexProjectionHead): boolean {
221
+ return left.incarnationId === right.incarnationId
222
+ && left.revision === right.revision
223
+ && left.contentRoot === right.contentRoot;
224
+ }
225
+
226
+ public async loadAuxiliarySummaryHead(
227
+ storageKey: string,
228
+ sessionId: string,
229
+ workspaceRequired: boolean,
230
+ ): Promise<{ projection: IFlexProjectionHead; summary: IFlexSessionAuxiliarySummary } | undefined> {
231
+ providerKey(storageKey, sessionId);
232
+ const projection = await this.loadHead(storageKey, sessionId);
233
+ if (!projection?.incarnationId) return undefined;
234
+ const slot = await this.records.read(
235
+ this.auxiliarySummaryAddress(storageKey, sessionId, workspaceRequired),
236
+ (value) => this.assertAuxiliarySummarySlot(value),
237
+ );
238
+ return slot && this.matchesProjection(slot.projection, projection)
239
+ ? { projection: slot.projection, summary: slot.summary }
240
+ : undefined;
241
+ }
242
+
243
+ public async saveAuxiliarySummaryHead(
244
+ storageKey: string,
245
+ sessionId: string,
246
+ expectedProjection: IFlexProjectionHead,
247
+ workspaceRequired: boolean,
248
+ summary: IFlexSessionAuxiliarySummary,
249
+ ): Promise<void> {
250
+ providerKey(storageKey, sessionId);
251
+ const address = this.auxiliarySummaryAddress(storageKey, sessionId, workspaceRequired);
252
+ if (!expectedProjection.incarnationId || !/^[a-f0-9]{64}$/u.test(expectedProjection.contentRoot)
253
+ || !Number.isSafeInteger(expectedProjection.revision) || expectedProjection.revision < 1) {
254
+ throw new FlexHarnessValidationError('A session auxiliary summary requires a rooted projection head.');
255
+ }
256
+ const validated = assertFlexSessionAuxiliarySummary(summary);
257
+ await this.records.mutate(address, {
258
+ validate: (value) => this.assertAuxiliarySummarySlot(value),
259
+ decide: (current) => {
260
+ if (current) {
261
+ if (this.matchesProjection(current.projection, expectedProjection)) {
262
+ if (canonicalJson(current.summary) !== canonicalJson(validated)) {
263
+ throw new FlexHarnessStoreFormatError('Conflicting auxiliary summary for one projection head.');
264
+ }
265
+ return undefined;
266
+ }
267
+ if (current.projection.incarnationId === expectedProjection.incarnationId
268
+ && current.projection.revision > expectedProjection.revision) return undefined;
269
+ }
270
+ const revision = (current?.revision ?? 0) + 1;
271
+ return { revision, value: { revision, projection: expectedProjection, summary: validated } };
272
+ },
273
+ contention: () => new FlexHarnessStoreFormatError('Contended auxiliary summary record.'),
274
+ });
275
+ }
276
+
178
277
  private log(sessionId: string): IFlexRecordLog<TFlexProjectionSnapshot, IFlexProjectionChange> {
179
278
  return {
180
279
  validate: (value) => {
@@ -217,7 +316,7 @@ class NoSqlProjectionStore implements IFlexProjectionStore {
217
316
 
218
317
  public deleteSession(storageKey: string, sessionId: string): Promise<void> {
219
318
  providerKey(storageKey, sessionId);
220
- return this.records.deleteOwner(storageKey, sessionId, ['projection']);
319
+ return this.records.deleteOwner(storageKey, sessionId, ['projection', 'sessionAuxiliarySummary']);
221
320
  }
222
321
  }
223
322
 
@@ -10,6 +10,7 @@ export type TFlexRecordDomain =
10
10
  | 'scope'
11
11
  | 'scopeRecovery'
12
12
  | 'projection'
13
+ | 'sessionAuxiliarySummary'
13
14
  | 'permission'
14
15
  | 'projectManagement'
15
16
  | 'agentEvents'