@modelprofile.com/flexharness 18.0.0 → 18.2.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.
Files changed (80) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.cachewarm.js +3 -3
  3. package/dist_ts/classes.flexharness.callbacks.d.ts +37 -0
  4. package/dist_ts/classes.flexharness.callbacks.js +129 -2
  5. package/dist_ts/classes.flexharness.compaction.js +2 -2
  6. package/dist_ts/classes.flexharness.configurations.js +4 -4
  7. package/dist_ts/classes.flexharness.core.d.ts +96 -5
  8. package/dist_ts/classes.flexharness.core.js +848 -301
  9. package/dist_ts/classes.flexharness.d.ts +10 -1
  10. package/dist_ts/classes.flexharness.deletion.d.ts +13 -0
  11. package/dist_ts/classes.flexharness.deletion.js +122 -40
  12. package/dist_ts/classes.flexharness.imports.js +26 -21
  13. package/dist_ts/classes.flexharness.js +16 -1
  14. package/dist_ts/classes.flexharness.lifecycle.js +9 -3
  15. package/dist_ts/classes.flexharness.projects.js +2 -2
  16. package/dist_ts/classes.flexharness.prompts.js +14 -8
  17. package/dist_ts/classes.flexharness.reversions.js +3 -3
  18. package/dist_ts/classes.flexharness.runs.js +18 -2
  19. package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
  20. package/dist_ts/classes.flexharness.sessions.js +40 -14
  21. package/dist_ts/classes.flexharness.slashcommands.js +3 -3
  22. package/dist_ts/classes.flexharness.subagents.js +37 -16
  23. package/dist_ts/classes.flexharness.tooldispatch.js +3 -3
  24. package/dist_ts/classes.scoperecovery.d.ts +36 -0
  25. package/dist_ts/classes.scoperecovery.js +228 -0
  26. package/dist_ts/classes.stores.d.ts +14 -1
  27. package/dist_ts/classes.stores.js +150 -17
  28. package/dist_ts/classes.timeslicer.d.ts +21 -0
  29. package/dist_ts/classes.timeslicer.js +31 -0
  30. package/dist_ts/index.d.ts +1 -0
  31. package/dist_ts/index.js +2 -1
  32. package/dist_ts/interfaces.d.ts +120 -0
  33. package/dist_ts/interfaces.flexharness.d.ts +56 -1
  34. package/dist_ts/interfaces.js +1 -1
  35. package/dist_ts/plugins.d.ts +2 -2
  36. package/dist_ts/plugins.js +3 -3
  37. package/dist_ts/utils.harnessoptions.d.ts +2 -0
  38. package/dist_ts/utils.harnessoptions.js +16 -11
  39. package/dist_ts/utils.json.d.ts +6 -0
  40. package/dist_ts/utils.json.js +75 -20
  41. package/dist_ts/utils.scopesnapshot.d.ts +14 -0
  42. package/dist_ts/utils.scopesnapshot.js +58 -0
  43. package/dist_ts_stores_nosqldb/classes.nosqldbstores.d.ts +3 -2
  44. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +33 -2
  45. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +10 -1
  46. package/dist_ts_stores_nosqldb/classes.recordstore.js +75 -7
  47. package/package.json +3 -3
  48. package/readme.md +46 -3
  49. package/ts/00_commitinfo_data.ts +1 -1
  50. package/ts/classes.flexharness.cachewarm.ts +2 -2
  51. package/ts/classes.flexharness.callbacks.ts +142 -1
  52. package/ts/classes.flexharness.compaction.ts +1 -1
  53. package/ts/classes.flexharness.configurations.ts +3 -3
  54. package/ts/classes.flexharness.core.ts +902 -328
  55. package/ts/classes.flexharness.deletion.ts +161 -52
  56. package/ts/classes.flexharness.imports.ts +26 -21
  57. package/ts/classes.flexharness.lifecycle.ts +8 -2
  58. package/ts/classes.flexharness.projects.ts +1 -1
  59. package/ts/classes.flexharness.prompts.ts +11 -7
  60. package/ts/classes.flexharness.reversions.ts +2 -2
  61. package/ts/classes.flexharness.runs.ts +16 -1
  62. package/ts/classes.flexharness.sessions.ts +43 -13
  63. package/ts/classes.flexharness.slashcommands.ts +2 -2
  64. package/ts/classes.flexharness.subagents.ts +40 -15
  65. package/ts/classes.flexharness.tooldispatch.ts +2 -2
  66. package/ts/classes.flexharness.ts +22 -0
  67. package/ts/classes.scoperecovery.ts +290 -0
  68. package/ts/classes.stores.ts +150 -16
  69. package/ts/classes.timeslicer.ts +32 -0
  70. package/ts/index.ts +2 -0
  71. package/ts/interfaces.flexharness.ts +60 -0
  72. package/ts/interfaces.ts +129 -0
  73. package/ts/plugins.ts +2 -0
  74. package/ts/readme.md +46 -3
  75. package/ts/utils.harnessoptions.ts +18 -12
  76. package/ts/utils.json.ts +70 -18
  77. package/ts/utils.scopesnapshot.ts +75 -0
  78. package/ts_stores_nosqldb/classes.nosqldbstores.ts +52 -2
  79. package/ts_stores_nosqldb/classes.recordstore.ts +78 -8
  80. package/ts_stores_nosqldb/readme.md +10 -0
@@ -63,9 +63,9 @@ export class FlexHarnessSessionDeletion<TScope> {
63
63
  const { scope, state } = await this.core.resolveState(scopeId);
64
64
  this.core.commands.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
65
65
  const plan = await this.core.withScopeMutationOwnership(state, async (): Promise<ISessionDeletionPlan> => {
66
- const stored = state.sessions.get(validated.root.sessionId);
67
- if (stored) {
68
- if (!matchesSessionGeneration(stored.session, validated.root)) {
66
+ const session = state.catalogue.get(validated.root.sessionId);
67
+ if (session) {
68
+ if (!matchesSessionGeneration(session, validated.root)) {
69
69
  return { matched: false };
70
70
  }
71
71
  const subtree = this.collectSessionSubtree(state, validated.root.sessionId);
@@ -75,16 +75,17 @@ export class FlexHarnessSessionDeletion<TScope> {
75
75
  );
76
76
  this.assertAuthorizedSessionGenerationCohort(
77
77
  [
78
- ...subtree.map((entry) => entry.session),
78
+ ...subtree,
79
79
  ...this.tombstonesForRoots(state, descendantRoots),
80
80
  ],
81
81
  validated.authorizedBySessionId,
82
82
  );
83
- const reservation = await this.core.mutateScopeOwned(state, () =>
83
+ const reservation = await this.reserveFencedSessionDeletion(state, scopeId, scope.scope, () =>
84
84
  this.reserveLiveSessionDeletion(
85
85
  state,
86
86
  validated.root.sessionId,
87
- stored,
87
+ session,
88
+ state.sessions.get(validated.root.sessionId),
88
89
  subtree,
89
90
  descendantRoots,
90
91
  ));
@@ -131,9 +132,25 @@ export class FlexHarnessSessionDeletion<TScope> {
131
132
  const { scope, state } = await this.core.resolveState(scopeId);
132
133
  this.core.commands.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
133
134
  validateIdentifier(sessionId, 'sessionId');
134
- await state.scopeQueue;
135
- this.core.imports.assertNoCommittingSessionImport(state, sessionId);
136
- return this.startSessionDeletion(state, scopeId, scope.scope, sessionId);
135
+ // Reserve the scope lane now, rather than waiting for its tail and yielding our FIFO slot.
136
+ const { deletion } = await this.core.withScopeMutationOwnership(state, async () => {
137
+ this.core.imports.assertNoCommittingSessionImport(state, sessionId);
138
+ const session = state.catalogue.get(sessionId);
139
+ if (!session) {
140
+ return { deletion: this.startSessionDeletion(state, scopeId, scope.scope, sessionId) };
141
+ }
142
+ const reservation = await this.reserveFencedSessionDeletion(state, scopeId, scope.scope, () =>
143
+ this.reserveLiveSessionDeletion(
144
+ state,
145
+ sessionId,
146
+ session,
147
+ state.sessions.get(sessionId),
148
+ this.collectSessionSubtree(state, sessionId),
149
+ this.descendantTombstoneRoots(state, sessionId),
150
+ ));
151
+ return { deletion: this.startReservedSessionDeletion(state, scopeId, scope.scope, sessionId, reservation) };
152
+ });
153
+ await deletion;
137
154
  }
138
155
 
139
156
  private startSessionDeletion(
@@ -207,39 +224,44 @@ export class FlexHarnessSessionDeletion<TScope> {
207
224
  private reserveLiveSessionDeletion(
208
225
  state: IStorageState,
209
226
  sessionId: string,
210
- stored: IStoredSessionState,
211
- subtree: readonly IStoredSessionState[],
227
+ session: IFlexSession,
228
+ stored: IStoredSessionState | undefined,
229
+ subtree: readonly IFlexSession[],
212
230
  descendantRoots: readonly string[],
213
231
  ): IReservedSessionDeletion {
214
- if (state.sessions.get(sessionId) !== stored) {
232
+ if (state.catalogue.get(sessionId) !== session || state.sessions.get(sessionId) !== stored) {
215
233
  throw new FlexHarnessNotFoundError('Session', sessionId);
216
234
  }
217
- const rootDepth = stored.session.depth ?? 0;
235
+ const rootDepth = session.depth ?? 0;
218
236
  const deletedAt = new Date().toISOString();
219
- const deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
237
+ const deletedSessions = subtree.map((entry) => cloneSerializable(entry));
220
238
  const provenanceBySessionId = new Map(subtree.map((entry) => [
221
- entry.session.sessionId,
222
- this.core.subagentTasks.createSubagentProvenance(state, entry.session),
239
+ entry.sessionId,
240
+ this.core.subagentTasks.createSubagentProvenance(state, entry),
223
241
  ]));
224
242
  for (const entry of subtree) {
225
- const entrySessionId = entry.session.sessionId;
243
+ const entrySessionId = entry.sessionId;
226
244
  const subagent = provenanceBySessionId.get(entrySessionId);
245
+ const stored = state.sessions.get(entrySessionId);
246
+ state.catalogue.delete(entrySessionId);
227
247
  state.sessions.delete(entrySessionId);
228
- state.retainedSessionCleanups.set(entrySessionId, {
229
- stored: entry,
230
- domainsCompleted: false,
231
- });
248
+ if (stored) {
249
+ state.retainedSessionCleanups.set(entrySessionId, {
250
+ stored,
251
+ domainsCompleted: false,
252
+ });
253
+ }
232
254
  state.tombstones.set(entrySessionId, {
233
255
  sessionId: entrySessionId,
234
- ...requireSessionGeneration(entry.session),
256
+ ...requireSessionGeneration(entry),
235
257
  deletedAt,
236
258
  rootSessionId: sessionId,
237
- depth: (entry.session.depth ?? rootDepth) - rootDepth,
238
- ...(entry.session.parentSessionId === undefined
259
+ depth: (entry.depth ?? rootDepth) - rootDepth,
260
+ ...(entry.parentSessionId === undefined
239
261
  ? {}
240
- : { parentSessionId: entry.session.parentSessionId }),
262
+ : { parentSessionId: entry.parentSessionId }),
241
263
  ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
242
- ...(entry.session.origin === undefined ? {} : { imported: true as const }),
264
+ ...(entry.origin === undefined ? {} : { imported: true as const }),
243
265
  });
244
266
  }
245
267
  return {
@@ -276,21 +298,81 @@ export class FlexHarnessSessionDeletion<TScope> {
276
298
  }
277
299
  return;
278
300
  }
279
- const stored = this.core.requireSession(state, sessionId);
280
- const reservation = await this.core.mutateScope(state, () => {
281
- const subtree = this.collectSessionSubtree(state, sessionId);
282
- const descendantRoots = this.descendantTombstoneRoots(state, sessionId);
283
- return this.reserveLiveSessionDeletion(
284
- state,
285
- sessionId,
286
- stored,
287
- subtree,
288
- descendantRoots,
289
- );
290
- });
301
+ const reservation = await this.core.withScopeMutationOwnership(state, () =>
302
+ this.reserveFencedSessionDeletion(state, scopeId, scope, () => {
303
+ const session = state.catalogue.get(sessionId);
304
+ if (!session) throw new FlexHarnessNotFoundError('Session', sessionId);
305
+ const subtree = this.collectSessionSubtree(state, sessionId);
306
+ const descendantRoots = this.descendantTombstoneRoots(state, sessionId);
307
+ return this.reserveLiveSessionDeletion(
308
+ state,
309
+ sessionId,
310
+ session,
311
+ state.sessions.get(sessionId),
312
+ subtree,
313
+ descendantRoots,
314
+ );
315
+ }));
291
316
  await this.finishReservedSessionDeletion(state, scopeId, scope, sessionId, reservation);
292
317
  }
293
318
 
319
+ /**
320
+ * Applies a deletion reservation in the scope lane its caller owns and fences the deleted
321
+ * sessions as soon as it is applied, before its scope save completes: their configuration
322
+ * resolutions are aborted and their runs cancelled at once, so an admission that has not reached
323
+ * its model call yet never does, however long the save takes. Their queued prompts are fenced by
324
+ * the reservation itself, since promotion refuses a session the scope no longer holds. A save
325
+ * that fails rolls the reservation back: the sessions stay, their runs cancelled.
326
+ */
327
+ private reserveFencedSessionDeletion(
328
+ state: IStorageState,
329
+ scopeId: string,
330
+ scope: TScope,
331
+ reserve: () => IReservedSessionDeletion,
332
+ ): Promise<IReservedSessionDeletion> {
333
+ let reserved: IReservedSessionDeletion | undefined;
334
+ // `mutateScopeOwned` applies the mutation before its first await, so the fence precedes the save.
335
+ const saved = this.core.mutateScopeOwned(state, () => {
336
+ reserved = reserve();
337
+ return reserved;
338
+ });
339
+ if (reserved) this.fenceDeletedSessions(state, scopeId, scope, reserved);
340
+ return saved;
341
+ }
342
+
343
+ /** Stops what runs for the reserved sessions; `finishReservedSessionDeletion` awaits it. */
344
+ private fenceDeletedSessions(
345
+ state: IStorageState,
346
+ scopeId: string,
347
+ scope: TScope,
348
+ reservation: IReservedSessionDeletion,
349
+ ): void {
350
+ const deletedSessionIds = reservation.deletedSessions.map((deleted) => deleted.sessionId);
351
+ this.core.cacheWarm.onSessionsDeleted(state, deletedSessionIds);
352
+ const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
353
+ reservation.configurationSettlement = this.core.configurations.abortSessionConfigurations(
354
+ state.storageKey,
355
+ reason,
356
+ new Set(deletedSessionIds),
357
+ );
358
+ for (const deleted of this.childFirst(reservation.deletedSessions)) {
359
+ const active = state.activeRuns.get(deleted.sessionId);
360
+ if (active) {
361
+ this.core.runs.cancelRun(
362
+ active,
363
+ reason,
364
+ this.core.compaction.createCompactorContext(scopeId, scope, state.storageKey, deleted.sessionId),
365
+ );
366
+ }
367
+ }
368
+ }
369
+
370
+ private childFirst(sessions: readonly IFlexSession[]): IFlexSession[] {
371
+ return [...sessions].sort((left, right) =>
372
+ (right.depth ?? 0) - (left.depth ?? 0)
373
+ || left.sessionId.localeCompare(right.sessionId));
374
+ }
375
+
294
376
  private async finishReservedSessionDeletion(
295
377
  state: IStorageState,
296
378
  scopeId: string,
@@ -307,6 +389,7 @@ export class FlexHarnessSessionDeletion<TScope> {
307
389
  new Set(deletedSessions.map((deleted) => deleted.sessionId)),
308
390
  );
309
391
  if (configurationSettlement) await configurationSettlement;
392
+ if (reservation.configurationSettlement) await reservation.configurationSettlement;
310
393
  const slashCommandErrors: unknown[] = [];
311
394
  for (const deleted of deletedSessions) {
312
395
  const listingSettlement = this.core.commands.abortSlashCommandListings(
@@ -322,9 +405,7 @@ export class FlexHarnessSessionDeletion<TScope> {
322
405
  deleted.sessionId,
323
406
  );
324
407
  }
325
- const childFirstDeletedSessions = [...deletedSessions].sort((left, right) =>
326
- (right.depth ?? 0) - (left.depth ?? 0)
327
- || left.sessionId.localeCompare(right.sessionId));
408
+ const childFirstDeletedSessions = this.childFirst(deletedSessions);
328
409
  for (const deleted of childFirstDeletedSessions) {
329
410
  const active = state.activeRuns.get(deleted.sessionId);
330
411
  if (active) {
@@ -400,8 +481,8 @@ export class FlexHarnessSessionDeletion<TScope> {
400
481
  private collectSessionSubtree(
401
482
  state: IStorageState,
402
483
  rootSessionId: string,
403
- ): IStoredSessionState[] {
404
- const subtree: IStoredSessionState[] = [];
484
+ ): IFlexSession[] {
485
+ const subtree: IFlexSession[] = [];
405
486
  const pending = [rootSessionId];
406
487
  const seen = new Set<string>();
407
488
  while (pending.length > 0) {
@@ -410,12 +491,12 @@ export class FlexHarnessSessionDeletion<TScope> {
410
491
  throw new FlexHarnessValidationError('Session relationships contain a cycle.');
411
492
  }
412
493
  seen.add(sessionId);
413
- const stored = state.sessions.get(sessionId);
414
- if (!stored) continue;
415
- subtree.push(stored);
416
- const children = [...state.sessions.values()]
417
- .filter((candidate) => candidate.session.parentSessionId === sessionId)
418
- .map((candidate) => candidate.session.sessionId)
494
+ const session = state.catalogue.get(sessionId);
495
+ if (!session) continue;
496
+ subtree.push(session);
497
+ const children = [...state.catalogue.values()]
498
+ .filter((candidate) => candidate.parentSessionId === sessionId)
499
+ .map((candidate) => candidate.sessionId)
419
500
  .sort()
420
501
  .reverse();
421
502
  pending.push(...children);
@@ -527,9 +608,14 @@ export class FlexHarnessSessionDeletion<TScope> {
527
608
  const run = state.activeRuns.get(sessionId);
528
609
  if (run) this.core.runs.cancelRun(run, reason, context);
529
610
  }
530
- await Promise.allSettled([...groupIds]
531
- .map((sessionId) => state.sessionInitializations.get(sessionId))
532
- .filter((completion): completion is Promise<void> => completion !== undefined));
611
+ await Promise.allSettled([...groupIds].flatMap((sessionId) => {
612
+ const completions: Promise<unknown>[] = [];
613
+ const initialization = state.sessionInitializations.get(sessionId);
614
+ const hydration = state.sessionLoads.get(sessionId);
615
+ if (initialization) completions.push(initialization);
616
+ if (hydration) completions.push(hydration);
617
+ return completions;
618
+ }));
533
619
  for (const tombstone of group) {
534
620
  const sessionId = tombstone.sessionId;
535
621
  const retained = state.retainedSessionCleanups.get(sessionId);
@@ -595,6 +681,7 @@ export class FlexHarnessSessionDeletion<TScope> {
595
681
  'Tombstone cleanup requires its exact scope context before deleting projection data.',
596
682
  );
597
683
  }
684
+ if (!retained) await this.setDeletionRecoveryRequired(state, sessionId, true);
598
685
  await this.core.reversions.releaseDeletedSessionReversions(
599
686
  state,
600
687
  state.storageKey,
@@ -607,6 +694,10 @@ export class FlexHarnessSessionDeletion<TScope> {
607
694
  if (retained) retained.domainsCompleted = true;
608
695
  }
609
696
  }
697
+ // Domains and reversion references are durably resolved. Clear the redundant sidecar bit
698
+ // while the durable tombstone still prevents reuse and remains a recovery owner on a crash.
699
+ // Removing the tombstone first would leave an unresolvable orphan bit if its clear failed.
700
+ for (const tombstone of group) await this.setDeletionRecoveryRequired(state, tombstone.sessionId, false);
610
701
  await this.core.mutateScope(state, () => {
611
702
  for (const tombstone of group) {
612
703
  state.tombstones.delete(tombstone.sessionId);
@@ -614,4 +705,22 @@ export class FlexHarnessSessionDeletion<TScope> {
614
705
  }
615
706
  }, true);
616
707
  }
708
+
709
+ private async setDeletionRecoveryRequired(
710
+ state: IStorageState,
711
+ sessionId: string,
712
+ required: boolean,
713
+ ): Promise<void> {
714
+ if (!state.sessionLocal) return;
715
+ if (!state.qualifyingLegacy) {
716
+ try {
717
+ await this.core.stores.scopes.sessionLocal!.setRecoveryRequired(state.storageKey, sessionId, required);
718
+ } catch (error) {
719
+ state.lifecycle = 'fenced';
720
+ throw error;
721
+ }
722
+ }
723
+ if (required) state.recoverySessionIds.add(sessionId);
724
+ else state.recoverySessionIds.delete(sessionId);
725
+ }
617
726
  }
@@ -51,7 +51,7 @@ export class FlexHarnessSessionImports<TScope> {
51
51
  ): Promise<TFlexBeginSessionImportResult> {
52
52
  this.core.assertOpen();
53
53
  const normalized = normalizeBeginSessionImportOptions(options);
54
- const { scope, state } = await this.core.resolveState(scopeId);
54
+ const { scope, state } = await this.core.resolveState(scopeId, normalized.parent?.sessionId);
55
55
  await state.scopeQueue;
56
56
  this.core.assertOpen();
57
57
  this.core.assertStateAcceptingWork(state);
@@ -62,17 +62,17 @@ export class FlexHarnessSessionImports<TScope> {
62
62
  throw new FlexHarnessSessionBusyError(staged.sessionId, 'is already being imported');
63
63
  }
64
64
  }
65
- for (const stored of state.sessions.values()) {
66
- const origin = stored.session.origin;
65
+ for (const session of state.catalogue.values()) {
66
+ const origin = session.origin;
67
67
  if (origin === undefined || sessionImportIdentity(origin) !== identity) continue;
68
68
  const existing: TFlexBeginSessionImportResult = {
69
69
  status: origin.digest === normalized.origin.digest ? 'already_imported' : 'digest_mismatch',
70
- session: stored.session,
70
+ session,
71
71
  };
72
72
  return publicSnapshot(existing);
73
73
  }
74
74
  if (
75
- state.sessions.has(sessionId)
75
+ state.catalogue.has(sessionId)
76
76
  || state.tombstones.has(sessionId)
77
77
  || state.initializingSessions.has(sessionId)
78
78
  ) {
@@ -186,10 +186,14 @@ export class FlexHarnessSessionImports<TScope> {
186
186
  let reserved = false;
187
187
  let loaded: IStoredSessionState | undefined;
188
188
  try {
189
+ // Transcript validation needs only this imported parent, before taking the scope lane.
190
+ if (options.parent) {
191
+ await this.core.hydrateSession(state, options.parent.sessionId, scopeId, scope);
192
+ }
189
193
  // A tombstone reserves the id while the projection is written, so a crash before the session
190
194
  // is published leaves only data that the next load or deletion cleans up.
191
195
  await this.core.mutateScope(state, () => {
192
- if (state.sessions.has(sessionId) || state.tombstones.has(sessionId)) {
196
+ if (state.catalogue.has(sessionId) || state.tombstones.has(sessionId)) {
193
197
  throw this.core.trustInternalError(new FlexHarnessValidationError(
194
198
  `Session "${sessionId}" already exists or is being deleted.`,
195
199
  ));
@@ -202,9 +206,9 @@ export class FlexHarnessSessionImports<TScope> {
202
206
  sessionId,
203
207
  sessionGenerationId: createSessionGenerationId(),
204
208
  sessionGenerationSequence: state.revision + 1,
205
- ...(parent?.session.configurationRef === undefined
209
+ ...(parent?.configurationRef === undefined
206
210
  ? {}
207
- : { configurationRef: parent.session.configurationRef }),
211
+ : { configurationRef: parent.configurationRef }),
208
212
  ...(options.title === undefined ? {} : { title: options.title }),
209
213
  createdAt: options.createdAt,
210
214
  updatedAt: options.updatedAt,
@@ -219,7 +223,7 @@ export class FlexHarnessSessionImports<TScope> {
219
223
  parentToolCallId: options.parent.toolCallId,
220
224
  agent: options.parent.agent,
221
225
  }),
222
- depth: parent === undefined ? 0 : (parent.session.depth ?? 0) + 1,
226
+ depth: parent === undefined ? 0 : (parent.depth ?? 0) + 1,
223
227
  origin,
224
228
  };
225
229
  state.tombstones.set(sessionId, {
@@ -247,7 +251,7 @@ export class FlexHarnessSessionImports<TScope> {
247
251
  loaded = runtime;
248
252
  await this.core.mutateScope(state, () => {
249
253
  if (
250
- state.sessions.has(sessionId)
254
+ state.catalogue.has(sessionId)
251
255
  || state.tombstones.get(sessionId)?.sessionGenerationId !== metadata.sessionGenerationId
252
256
  ) {
253
257
  throw this.core.trustInternalError(new FlexHarnessAbortError(
@@ -372,17 +376,18 @@ export class FlexHarnessSessionImports<TScope> {
372
376
  state: IStorageState,
373
377
  sessionId: string,
374
378
  parent: NonNullable<INormalizedSessionImportOptions['parent']>,
375
- ): IStoredSessionState {
376
- const parentStored = state.initializingSessions.has(parent.sessionId)
379
+ ): IFlexSession {
380
+ const parentMetadata = state.initializingSessions.has(parent.sessionId)
377
381
  || state.tombstones.has(parent.sessionId)
378
382
  ? undefined
379
- : state.sessions.get(parent.sessionId);
380
- if (!parentStored?.session.origin) {
383
+ : state.catalogue.get(parent.sessionId);
384
+ const parentStored = state.sessions.get(parent.sessionId);
385
+ if (!parentMetadata?.origin || !parentStored) {
381
386
  throw this.core.trustInternalError(new FlexHarnessValidationError(
382
387
  `The parent of imported session "${sessionId}" must be a committed imported session.`,
383
388
  ));
384
389
  }
385
- if ((parentStored.session.depth ?? 0) + 1 > FLEX_SESSION_IMPORT_MAX_DEPTH) {
390
+ if ((parentMetadata.depth ?? 0) + 1 > FLEX_SESSION_IMPORT_MAX_DEPTH) {
386
391
  throw this.core.trustInternalError(new FlexHarnessValidationError(
387
392
  `Imported sessions nest at most ${FLEX_SESSION_IMPORT_MAX_DEPTH} levels deep.`,
388
393
  ));
@@ -399,17 +404,17 @@ export class FlexHarnessSessionImports<TScope> {
399
404
  `Parent run "${parent.runId}" has no tool call "${parent.toolCallId}" whose childSessionId is "${sessionId}".`,
400
405
  ));
401
406
  }
402
- for (const stored of state.sessions.values()) {
407
+ for (const session of state.catalogue.values()) {
403
408
  if (
404
- stored.session.parentSessionId === parent.sessionId
405
- && stored.session.parentRunId === parent.runId
406
- && stored.session.parentToolCallId === parent.toolCallId
409
+ session.parentSessionId === parent.sessionId
410
+ && session.parentRunId === parent.runId
411
+ && session.parentToolCallId === parent.toolCallId
407
412
  ) {
408
413
  throw this.core.trustInternalError(new FlexHarnessValidationError(
409
- `Session "${stored.session.sessionId}" already belongs to tool call "${parent.toolCallId}".`,
414
+ `Session "${session.sessionId}" already belongs to tool call "${parent.toolCallId}".`,
410
415
  ));
411
416
  }
412
417
  }
413
- return parentStored;
418
+ return parentMetadata;
414
419
  }
415
420
  }
@@ -80,6 +80,7 @@ export class FlexHarnessLifecycle<TScope> {
80
80
  state.fenceInProgress = true;
81
81
  state.lifecycle = 'fenced';
82
82
  this.core.cacheWarm.onStateRetiring(state);
83
+ this.core.callbacks.closeCheckpoints(state);
83
84
  const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.'));
84
85
  if (!state.compactorLifecycleController.signal.aborted) {
85
86
  state.compactorLifecycleController.abort(reason);
@@ -140,7 +141,7 @@ export class FlexHarnessLifecycle<TScope> {
140
141
  ...state.delegatedRunAdmissionOwners,
141
142
  ]));
142
143
  const detachedCleanupAttempts = this.core.providers.beginDetachedCleanupSettlement(state);
143
- await Promise.allSettled([...state.sessionInitializations.values()]);
144
+ await Promise.allSettled([...state.sessionInitializations.values(), ...state.sessionLoads.values(), ...(state.sharedRecovery ? [state.sharedRecovery] : [])]);
144
145
  cleanupErrors.push(...await this.closeOrphanedResources(state.storageKey));
145
146
  await state.scopeQueue;
146
147
  await this.core.projects.awaitProjectManagementOperations(
@@ -214,6 +215,7 @@ export class FlexHarnessLifecycle<TScope> {
214
215
  if (cleanupErrors.length > 0) throw combineErrors([cause, ...cleanupErrors]);
215
216
  state.lifecycle = 'retired';
216
217
  state.sessions.clear();
218
+ state.sessionLoads.clear();
217
219
  const currentRetainedCleanups = [...state.retainedSessionCleanups]
218
220
  .filter(([sessionId]) => currentTombstoneSessions.has(sessionId));
219
221
  state.retainedSessionCleanups.clear();
@@ -230,6 +232,7 @@ export class FlexHarnessLifecycle<TScope> {
230
232
  state.pendingPermissions.clear();
231
233
  state.initializingSessions.clear();
232
234
  state.sessionInitializations.clear();
235
+ this.core.stores.scopes.sessionLocal?.releaseOwnership(state.storageKey);
233
236
  this.core.stateLoads.delete(state.storageKey);
234
237
  if (
235
238
  this.storageCompactorLifecycleControllers.get(state.storageKey)
@@ -565,6 +568,7 @@ export class FlexHarnessLifecycle<TScope> {
565
568
  completed = true;
566
569
  }).finally(() => {
567
570
  if (completed && this.core.stateLoads.get(storageKey) === stateLoad) {
571
+ this.core.stores.scopes.sessionLocal?.releaseOwnership(storageKey);
568
572
  this.core.stateLoads.delete(storageKey);
569
573
  if (this.storageCompactorLifecycleControllers.get(storageKey) === compactorController) {
570
574
  this.storageCompactorLifecycleControllers.delete(storageKey);
@@ -592,6 +596,7 @@ export class FlexHarnessLifecycle<TScope> {
592
596
  }
593
597
  if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
594
598
  this.core.cacheWarm.onStateRetiring(state);
599
+ this.core.callbacks.closeCheckpoints(state);
595
600
  const configurationSettlement = this.core.configurations.abortSessionConfigurations(storageKey, reason);
596
601
  if (configurationSettlement) await configurationSettlement;
597
602
  for (const staged of [...state.sessionImports.values()]) {
@@ -644,7 +649,7 @@ export class FlexHarnessLifecycle<TScope> {
644
649
  ));
645
650
  }
646
651
  }
647
- await Promise.allSettled([...state.sessionInitializations.values()]);
652
+ await Promise.allSettled([...state.sessionInitializations.values(), ...state.sessionLoads.values(), ...(state.sharedRecovery ? [state.sharedRecovery] : [])]);
648
653
  errors.push(...await this.closeOrphanedResources(state.storageKey));
649
654
  await state.scopeQueue;
650
655
  await this.core.projects.awaitProjectManagementOperations(
@@ -721,6 +726,7 @@ export class FlexHarnessLifecycle<TScope> {
721
726
  if (errors.length > 0) throw combineErrors(errors);
722
727
  state.lifecycle = 'retired';
723
728
  state.sessions.clear();
729
+ state.sessionLoads.clear();
724
730
  state.retainedSessionCleanups.clear();
725
731
  state.sessionDeletions.clear();
726
732
  state.tombstoneCleanups.clear();
@@ -267,7 +267,7 @@ export class FlexHarnessProjectManagement<TScope> {
267
267
  access: 'read' | 'write',
268
268
  ): Promise<{ state: IStorageState; stored: IStoredSessionState }> {
269
269
  this.requireProjectManagementTools();
270
- const { state } = await this.core.resolveState(scopeId);
270
+ const { state } = await this.core.resolveState(scopeId, sessionId);
271
271
  await state.scopeQueue;
272
272
  this.core.assertOpen();
273
273
  this.core.assertStateAcceptingWork(state);
@@ -252,7 +252,7 @@ export class FlexHarnessPromptQueue<TScope> {
252
252
  ): Promise<IFlexPromptQueueEntry> {
253
253
  validateIdentifier(queueId, 'queueId');
254
254
  requireTransferIdentifier(queueId, 'queueId');
255
- const { state } = await this.core.resolveState(scopeId);
255
+ const { state } = await this.core.resolveState(scopeId, sessionId);
256
256
  this.core.assertStateAcceptingWork(state);
257
257
  const stored = this.core.requireSession(state, sessionId);
258
258
  const entry = this.promptQueueEntry(stored, queueId);
@@ -264,7 +264,7 @@ export class FlexHarnessPromptQueue<TScope> {
264
264
  scopeId: string,
265
265
  sessionId: string,
266
266
  ): Promise<IFlexPromptQueueEntry[]> {
267
- const { state } = await this.core.resolveState(scopeId);
267
+ const { state } = await this.core.resolveState(scopeId, sessionId);
268
268
  this.core.assertStateAcceptingWork(state);
269
269
  const stored = this.core.requireSession(state, sessionId);
270
270
  return publicSnapshot([
@@ -280,7 +280,7 @@ export class FlexHarnessPromptQueue<TScope> {
280
280
  ): Promise<boolean> {
281
281
  validateIdentifier(queueId, 'queueId');
282
282
  requireTransferIdentifier(queueId, 'queueId');
283
- const { scope, state } = await this.core.resolveState(scopeId);
283
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
284
284
  const stored = this.core.requireSession(state, sessionId);
285
285
  const queued = stored.outstandingPromptsById.get(queueId);
286
286
  if (!queued) {
@@ -305,7 +305,7 @@ export class FlexHarnessPromptQueue<TScope> {
305
305
  scheduleKey: string,
306
306
  ): Promise<boolean> {
307
307
  validateIdentifier(scheduleKey, 'scheduleKey');
308
- const { scope, state } = await this.core.resolveState(scopeId);
308
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
309
309
  const stored = this.core.requireSession(state, sessionId);
310
310
  const queued = [...stored.outstandingPromptsById.values()]
311
311
  .find((entry) => entry.scheduleKey === scheduleKey);
@@ -331,7 +331,7 @@ export class FlexHarnessPromptQueue<TScope> {
331
331
  this.core.assertOpen();
332
332
  const prompt = normalizeFlexPrompt(steer.prompt, this.core.attachmentReferenceProtocols);
333
333
  const byteSize = this.promptAdmissionByteSize(steer.prompt, {});
334
- const { state } = await this.core.resolveState(scopeId);
334
+ const { state } = await this.core.resolveState(scopeId, sessionId);
335
335
  this.core.assertStateAcceptingWork(state);
336
336
  const stored = this.core.requireSession(state, sessionId);
337
337
  this.core.assertSessionWritable(stored);
@@ -462,7 +462,7 @@ export class FlexHarnessPromptQueue<TScope> {
462
462
  if (admissionSignals.some((signal) => signal.aborted)) abortAdmission();
463
463
  });
464
464
  try {
465
- const resolved = await Promise.race([this.core.resolveState(scopeId), abortPromise]);
465
+ const resolved = await Promise.race([this.core.resolveState(scopeId, sessionId), abortPromise]);
466
466
  const state = resolved.state;
467
467
  await Promise.race([state.scopeQueue, abortPromise]);
468
468
  if (admissionSignal?.aborted) {
@@ -657,7 +657,9 @@ export class FlexHarnessPromptQueue<TScope> {
657
657
  } catch (error) {
658
658
  if (state.activeRuns.get(queued.sessionId) === run) state.activeRuns.delete(queued.sessionId);
659
659
  const cancellation = isAbortError(error);
660
+ // The prompt's one outcome is recorded first; the obligation update cannot replace it.
660
661
  this.finishQueuedPrompt(queued, cancellation ? 'cancelled' : 'failed', error);
662
+ if (state.sessionLocal) await this.core.settleRecoveryObligation(state, stored);
661
663
  if (state.lifecycle !== 'active') return;
662
664
  }
663
665
  }
@@ -732,6 +734,7 @@ export class FlexHarnessPromptQueue<TScope> {
732
734
  this.assertPromptPromotion(queued, run);
733
735
  // A cache-warm exchange is model-visible only to its own model calls.
734
736
  const beginOptions = { generationId: run.runId, ...(run.cacheWarm ? { ephemeral: true as const } : {}) };
737
+ if (run.state.sessionLocal) await this.core.updateRecoveryObligation(run.state, run.stored, true);
735
738
  run.transaction = await this.core.compaction.withRunCompactorContext(
736
739
  run,
737
740
  () => generationPrompt === undefined
@@ -742,6 +745,7 @@ export class FlexHarnessPromptQueue<TScope> {
742
745
  const reservation = this.core.runs.createReservation(run, prompt, queued.promptId);
743
746
  closeReservationPublication = this.core.openPublication(run.state, run.sessionId);
744
747
  run.metricsOperation = createSessionMetricsOperation(run.runId, 'generation');
748
+ // The run's first save of its assistant message: its first checkpoint counts from it.
745
749
  await this.core.mutateProjection(run.state, run.stored, () => {
746
750
  if (run.stored.metrics.pendingGenerationId !== undefined) {
747
751
  throw new Error('Session metrics already owns a generation.');
@@ -778,7 +782,7 @@ export class FlexHarnessPromptQueue<TScope> {
778
782
  };
779
783
  }
780
784
  }
781
- });
785
+ }, false, (startedAt, completedAt) => this.core.callbacks.setCheckpointReference(run, startedAt, completedAt));
782
786
  projectionReserved = true;
783
787
  if (reservation.userMessage) run.reservedUserMessage = publicSnapshot(reservation.userMessage);
784
788
  run.reservedAssistantMessage = publicSnapshot(reservation.assistantMessage);
@@ -56,7 +56,7 @@ export class FlexHarnessReversions<TScope> {
56
56
  scopeId: string,
57
57
  sessionId: string,
58
58
  ): Promise<IFlexSessionReversionInfo> {
59
- const { state } = await this.core.resolveState(scopeId);
59
+ const { state } = await this.core.resolveState(scopeId, sessionId);
60
60
  const stored = this.core.requireSession(state, sessionId);
61
61
  await stored.projectionQueue;
62
62
  this.core.assertStateAcceptingWork(state);
@@ -273,7 +273,7 @@ export class FlexHarnessReversions<TScope> {
273
273
  direction: 'undo' | 'redo',
274
274
  signal?: AbortSignal,
275
275
  ): Promise<string> {
276
- const { scope, state } = await this.core.resolveState(scopeId);
276
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
277
277
  return this.changeReversionCursorResolved(
278
278
  scopeId,
279
279
  sessionId,