@modelprofile.com/flexharness 18.1.0 → 18.3.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 (68) 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 +39 -4
  8. package/dist_ts/classes.flexharness.core.js +467 -134
  9. package/dist_ts/classes.flexharness.d.ts +4 -0
  10. package/dist_ts/classes.flexharness.deletion.d.ts +13 -0
  11. package/dist_ts/classes.flexharness.deletion.js +132 -48
  12. package/dist_ts/classes.flexharness.imports.js +26 -21
  13. package/dist_ts/classes.flexharness.js +9 -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 +1 -1
  20. package/dist_ts/classes.flexharness.sessions.js +18 -18
  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 +37 -0
  25. package/dist_ts/classes.scoperecovery.js +229 -0
  26. package/dist_ts/classes.stores.d.ts +14 -1
  27. package/dist_ts/classes.stores.js +150 -17
  28. package/dist_ts/index.d.ts +1 -0
  29. package/dist_ts/index.js +2 -1
  30. package/dist_ts/interfaces.d.ts +113 -2
  31. package/dist_ts/interfaces.flexharness.d.ts +41 -5
  32. package/dist_ts/interfaces.js +1 -1
  33. package/dist_ts/utils.harnessoptions.d.ts +2 -0
  34. package/dist_ts/utils.harnessoptions.js +16 -11
  35. package/dist_ts_stores_nosqldb/classes.nosqldbstores.d.ts +3 -2
  36. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +33 -2
  37. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +10 -1
  38. package/dist_ts_stores_nosqldb/classes.recordstore.js +75 -7
  39. package/package.json +3 -3
  40. package/readme.md +43 -5
  41. package/ts/00_commitinfo_data.ts +1 -1
  42. package/ts/classes.flexharness.cachewarm.ts +2 -2
  43. package/ts/classes.flexharness.callbacks.ts +142 -1
  44. package/ts/classes.flexharness.compaction.ts +1 -1
  45. package/ts/classes.flexharness.configurations.ts +3 -3
  46. package/ts/classes.flexharness.core.ts +463 -133
  47. package/ts/classes.flexharness.deletion.ts +178 -62
  48. package/ts/classes.flexharness.imports.ts +26 -21
  49. package/ts/classes.flexharness.lifecycle.ts +8 -2
  50. package/ts/classes.flexharness.projects.ts +1 -1
  51. package/ts/classes.flexharness.prompts.ts +11 -7
  52. package/ts/classes.flexharness.reversions.ts +2 -2
  53. package/ts/classes.flexharness.runs.ts +16 -1
  54. package/ts/classes.flexharness.sessions.ts +17 -17
  55. package/ts/classes.flexharness.slashcommands.ts +2 -2
  56. package/ts/classes.flexharness.subagents.ts +40 -15
  57. package/ts/classes.flexharness.tooldispatch.ts +2 -2
  58. package/ts/classes.flexharness.ts +13 -0
  59. package/ts/classes.scoperecovery.ts +291 -0
  60. package/ts/classes.stores.ts +150 -16
  61. package/ts/index.ts +2 -0
  62. package/ts/interfaces.flexharness.ts +44 -4
  63. package/ts/interfaces.ts +124 -2
  64. package/ts/readme.md +43 -5
  65. package/ts/utils.harnessoptions.ts +18 -12
  66. package/ts_stores_nosqldb/classes.nosqldbstores.ts +52 -2
  67. package/ts_stores_nosqldb/classes.recordstore.ts +78 -8
  68. package/ts_stores_nosqldb/readme.md +10 -0
@@ -7,6 +7,7 @@ import type {
7
7
  IFlexAgentContextInvocation,
8
8
  IFlexDeleteSessionGenerationCohortInput,
9
9
  IFlexDeleteSessionGenerationCohortResult,
10
+ IFlexDeleteSessionGenerationCohortSuperseded,
10
11
  IFlexSession,
11
12
  IFlexSessionGeneration,
12
13
  IFlexSessionGenerationCohortEntry,
@@ -22,7 +23,7 @@ import type {
22
23
  IStoredSessionState,
23
24
  IRetainedSessionCleanup,
24
25
  IStorageState,
25
- ISessionDeletionPlan,
26
+ TSessionDeletionPlan,
26
27
  IReservedSessionDeletion,
27
28
  } from './interfaces.flexharness.js';
28
29
  import { requireSessionGeneration, combineErrors } from './utils.flexharness.js';
@@ -40,6 +41,16 @@ function matchesSessionGeneration(
40
41
  && actual.sessionGenerationSequence === expected.sessionGenerationSequence;
41
42
  }
42
43
 
44
+ /** The answer for a root whose session id another generation holds, live or tombstoned. */
45
+ function supersededBy(
46
+ holder: Pick<
47
+ IFlexSession | IFlexSessionTombstone,
48
+ 'sessionGenerationId' | 'sessionGenerationSequence'
49
+ >,
50
+ ): IFlexDeleteSessionGenerationCohortSuperseded {
51
+ return { matched: false, reason: 'superseded', current: requireSessionGeneration(holder) };
52
+ }
53
+
43
54
  /**
44
55
  * Session deletion: reservations, subtree tombstones and the cleanup of every domain a session
45
56
  * owns.
@@ -62,12 +73,10 @@ export class FlexHarnessSessionDeletion<TScope> {
62
73
  });
63
74
  const { scope, state } = await this.core.resolveState(scopeId);
64
75
  this.core.commands.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
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)) {
69
- return { matched: false };
70
- }
76
+ const plan = await this.core.withScopeMutationOwnership(state, async (): Promise<TSessionDeletionPlan> => {
77
+ const session = state.catalogue.get(validated.root.sessionId);
78
+ if (session) {
79
+ if (!matchesSessionGeneration(session, validated.root)) return supersededBy(session);
71
80
  const subtree = this.collectSessionSubtree(state, validated.root.sessionId);
72
81
  const descendantRoots = this.descendantTombstoneRoots(
73
82
  state,
@@ -75,16 +84,17 @@ export class FlexHarnessSessionDeletion<TScope> {
75
84
  );
76
85
  this.assertAuthorizedSessionGenerationCohort(
77
86
  [
78
- ...subtree.map((entry) => entry.session),
87
+ ...subtree,
79
88
  ...this.tombstonesForRoots(state, descendantRoots),
80
89
  ],
81
90
  validated.authorizedBySessionId,
82
91
  );
83
- const reservation = await this.core.mutateScopeOwned(state, () =>
92
+ const reservation = await this.reserveFencedSessionDeletion(state, scopeId, scope.scope, () =>
84
93
  this.reserveLiveSessionDeletion(
85
94
  state,
86
95
  validated.root.sessionId,
87
- stored,
96
+ session,
97
+ state.sessions.get(validated.root.sessionId),
88
98
  subtree,
89
99
  descendantRoots,
90
100
  ));
@@ -100,9 +110,8 @@ export class FlexHarnessSessionDeletion<TScope> {
100
110
  };
101
111
  }
102
112
  const tombstone = state.tombstones.get(validated.root.sessionId);
103
- if (!tombstone || !matchesSessionGeneration(tombstone, validated.root)) {
104
- return { matched: false };
105
- }
113
+ if (!tombstone) return { matched: false, reason: 'absent' };
114
+ if (!matchesSessionGeneration(tombstone, validated.root)) return supersededBy(tombstone);
106
115
  this.core.imports.assertNoCommittingSessionImport(state, validated.root.sessionId);
107
116
  const rootSessionId = tombstone.rootSessionId ?? tombstone.sessionId;
108
117
  const descendantRoots = this.descendantTombstoneRoots(state, rootSessionId);
@@ -120,10 +129,9 @@ export class FlexHarnessSessionDeletion<TScope> {
120
129
  ),
121
130
  };
122
131
  });
123
- if (!plan.matched) return publicSnapshot({ matched: false });
124
- if (!plan.deletion) throw new Error('Matched session deletion has no cleanup operation.');
132
+ if (!plan.matched) return publicSnapshot(plan);
125
133
  await plan.deletion;
126
- return publicSnapshot({ matched: true });
134
+ return publicSnapshot<IFlexDeleteSessionGenerationCohortResult>({ matched: true });
127
135
  }
128
136
 
129
137
  public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
@@ -131,9 +139,25 @@ export class FlexHarnessSessionDeletion<TScope> {
131
139
  const { scope, state } = await this.core.resolveState(scopeId);
132
140
  this.core.commands.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
133
141
  validateIdentifier(sessionId, 'sessionId');
134
- await state.scopeQueue;
135
- this.core.imports.assertNoCommittingSessionImport(state, sessionId);
136
- return this.startSessionDeletion(state, scopeId, scope.scope, sessionId);
142
+ // Reserve the scope lane now, rather than waiting for its tail and yielding our FIFO slot.
143
+ const { deletion } = await this.core.withScopeMutationOwnership(state, async () => {
144
+ this.core.imports.assertNoCommittingSessionImport(state, sessionId);
145
+ const session = state.catalogue.get(sessionId);
146
+ if (!session) {
147
+ return { deletion: this.startSessionDeletion(state, scopeId, scope.scope, sessionId) };
148
+ }
149
+ const reservation = await this.reserveFencedSessionDeletion(state, scopeId, scope.scope, () =>
150
+ this.reserveLiveSessionDeletion(
151
+ state,
152
+ sessionId,
153
+ session,
154
+ state.sessions.get(sessionId),
155
+ this.collectSessionSubtree(state, sessionId),
156
+ this.descendantTombstoneRoots(state, sessionId),
157
+ ));
158
+ return { deletion: this.startReservedSessionDeletion(state, scopeId, scope.scope, sessionId, reservation) };
159
+ });
160
+ await deletion;
137
161
  }
138
162
 
139
163
  private startSessionDeletion(
@@ -207,39 +231,44 @@ export class FlexHarnessSessionDeletion<TScope> {
207
231
  private reserveLiveSessionDeletion(
208
232
  state: IStorageState,
209
233
  sessionId: string,
210
- stored: IStoredSessionState,
211
- subtree: readonly IStoredSessionState[],
234
+ session: IFlexSession,
235
+ stored: IStoredSessionState | undefined,
236
+ subtree: readonly IFlexSession[],
212
237
  descendantRoots: readonly string[],
213
238
  ): IReservedSessionDeletion {
214
- if (state.sessions.get(sessionId) !== stored) {
239
+ if (state.catalogue.get(sessionId) !== session || state.sessions.get(sessionId) !== stored) {
215
240
  throw new FlexHarnessNotFoundError('Session', sessionId);
216
241
  }
217
- const rootDepth = stored.session.depth ?? 0;
242
+ const rootDepth = session.depth ?? 0;
218
243
  const deletedAt = new Date().toISOString();
219
- const deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
244
+ const deletedSessions = subtree.map((entry) => cloneSerializable(entry));
220
245
  const provenanceBySessionId = new Map(subtree.map((entry) => [
221
- entry.session.sessionId,
222
- this.core.subagentTasks.createSubagentProvenance(state, entry.session),
246
+ entry.sessionId,
247
+ this.core.subagentTasks.createSubagentProvenance(state, entry),
223
248
  ]));
224
249
  for (const entry of subtree) {
225
- const entrySessionId = entry.session.sessionId;
250
+ const entrySessionId = entry.sessionId;
226
251
  const subagent = provenanceBySessionId.get(entrySessionId);
252
+ const stored = state.sessions.get(entrySessionId);
253
+ state.catalogue.delete(entrySessionId);
227
254
  state.sessions.delete(entrySessionId);
228
- state.retainedSessionCleanups.set(entrySessionId, {
229
- stored: entry,
230
- domainsCompleted: false,
231
- });
255
+ if (stored) {
256
+ state.retainedSessionCleanups.set(entrySessionId, {
257
+ stored,
258
+ domainsCompleted: false,
259
+ });
260
+ }
232
261
  state.tombstones.set(entrySessionId, {
233
262
  sessionId: entrySessionId,
234
- ...requireSessionGeneration(entry.session),
263
+ ...requireSessionGeneration(entry),
235
264
  deletedAt,
236
265
  rootSessionId: sessionId,
237
- depth: (entry.session.depth ?? rootDepth) - rootDepth,
238
- ...(entry.session.parentSessionId === undefined
266
+ depth: (entry.depth ?? rootDepth) - rootDepth,
267
+ ...(entry.parentSessionId === undefined
239
268
  ? {}
240
- : { parentSessionId: entry.session.parentSessionId }),
269
+ : { parentSessionId: entry.parentSessionId }),
241
270
  ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
242
- ...(entry.session.origin === undefined ? {} : { imported: true as const }),
271
+ ...(entry.origin === undefined ? {} : { imported: true as const }),
243
272
  });
244
273
  }
245
274
  return {
@@ -276,21 +305,81 @@ export class FlexHarnessSessionDeletion<TScope> {
276
305
  }
277
306
  return;
278
307
  }
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
- });
308
+ const reservation = await this.core.withScopeMutationOwnership(state, () =>
309
+ this.reserveFencedSessionDeletion(state, scopeId, scope, () => {
310
+ const session = state.catalogue.get(sessionId);
311
+ if (!session) throw new FlexHarnessNotFoundError('Session', sessionId);
312
+ const subtree = this.collectSessionSubtree(state, sessionId);
313
+ const descendantRoots = this.descendantTombstoneRoots(state, sessionId);
314
+ return this.reserveLiveSessionDeletion(
315
+ state,
316
+ sessionId,
317
+ session,
318
+ state.sessions.get(sessionId),
319
+ subtree,
320
+ descendantRoots,
321
+ );
322
+ }));
291
323
  await this.finishReservedSessionDeletion(state, scopeId, scope, sessionId, reservation);
292
324
  }
293
325
 
326
+ /**
327
+ * Applies a deletion reservation in the scope lane its caller owns and fences the deleted
328
+ * sessions as soon as it is applied, before its scope save completes: their configuration
329
+ * resolutions are aborted and their runs cancelled at once, so an admission that has not reached
330
+ * its model call yet never does, however long the save takes. Their queued prompts are fenced by
331
+ * the reservation itself, since promotion refuses a session the scope no longer holds. A save
332
+ * that fails rolls the reservation back: the sessions stay, their runs cancelled.
333
+ */
334
+ private reserveFencedSessionDeletion(
335
+ state: IStorageState,
336
+ scopeId: string,
337
+ scope: TScope,
338
+ reserve: () => IReservedSessionDeletion,
339
+ ): Promise<IReservedSessionDeletion> {
340
+ let reserved: IReservedSessionDeletion | undefined;
341
+ // `mutateScopeOwned` applies the mutation before its first await, so the fence precedes the save.
342
+ const saved = this.core.mutateScopeOwned(state, () => {
343
+ reserved = reserve();
344
+ return reserved;
345
+ });
346
+ if (reserved) this.fenceDeletedSessions(state, scopeId, scope, reserved);
347
+ return saved;
348
+ }
349
+
350
+ /** Stops what runs for the reserved sessions; `finishReservedSessionDeletion` awaits it. */
351
+ private fenceDeletedSessions(
352
+ state: IStorageState,
353
+ scopeId: string,
354
+ scope: TScope,
355
+ reservation: IReservedSessionDeletion,
356
+ ): void {
357
+ const deletedSessionIds = reservation.deletedSessions.map((deleted) => deleted.sessionId);
358
+ this.core.cacheWarm.onSessionsDeleted(state, deletedSessionIds);
359
+ const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
360
+ reservation.configurationSettlement = this.core.configurations.abortSessionConfigurations(
361
+ state.storageKey,
362
+ reason,
363
+ new Set(deletedSessionIds),
364
+ );
365
+ for (const deleted of this.childFirst(reservation.deletedSessions)) {
366
+ const active = state.activeRuns.get(deleted.sessionId);
367
+ if (active) {
368
+ this.core.runs.cancelRun(
369
+ active,
370
+ reason,
371
+ this.core.compaction.createCompactorContext(scopeId, scope, state.storageKey, deleted.sessionId),
372
+ );
373
+ }
374
+ }
375
+ }
376
+
377
+ private childFirst(sessions: readonly IFlexSession[]): IFlexSession[] {
378
+ return [...sessions].sort((left, right) =>
379
+ (right.depth ?? 0) - (left.depth ?? 0)
380
+ || left.sessionId.localeCompare(right.sessionId));
381
+ }
382
+
294
383
  private async finishReservedSessionDeletion(
295
384
  state: IStorageState,
296
385
  scopeId: string,
@@ -307,6 +396,7 @@ export class FlexHarnessSessionDeletion<TScope> {
307
396
  new Set(deletedSessions.map((deleted) => deleted.sessionId)),
308
397
  );
309
398
  if (configurationSettlement) await configurationSettlement;
399
+ if (reservation.configurationSettlement) await reservation.configurationSettlement;
310
400
  const slashCommandErrors: unknown[] = [];
311
401
  for (const deleted of deletedSessions) {
312
402
  const listingSettlement = this.core.commands.abortSlashCommandListings(
@@ -322,9 +412,7 @@ export class FlexHarnessSessionDeletion<TScope> {
322
412
  deleted.sessionId,
323
413
  );
324
414
  }
325
- const childFirstDeletedSessions = [...deletedSessions].sort((left, right) =>
326
- (right.depth ?? 0) - (left.depth ?? 0)
327
- || left.sessionId.localeCompare(right.sessionId));
415
+ const childFirstDeletedSessions = this.childFirst(deletedSessions);
328
416
  for (const deleted of childFirstDeletedSessions) {
329
417
  const active = state.activeRuns.get(deleted.sessionId);
330
418
  if (active) {
@@ -400,8 +488,8 @@ export class FlexHarnessSessionDeletion<TScope> {
400
488
  private collectSessionSubtree(
401
489
  state: IStorageState,
402
490
  rootSessionId: string,
403
- ): IStoredSessionState[] {
404
- const subtree: IStoredSessionState[] = [];
491
+ ): IFlexSession[] {
492
+ const subtree: IFlexSession[] = [];
405
493
  const pending = [rootSessionId];
406
494
  const seen = new Set<string>();
407
495
  while (pending.length > 0) {
@@ -410,12 +498,12 @@ export class FlexHarnessSessionDeletion<TScope> {
410
498
  throw new FlexHarnessValidationError('Session relationships contain a cycle.');
411
499
  }
412
500
  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)
501
+ const session = state.catalogue.get(sessionId);
502
+ if (!session) continue;
503
+ subtree.push(session);
504
+ const children = [...state.catalogue.values()]
505
+ .filter((candidate) => candidate.parentSessionId === sessionId)
506
+ .map((candidate) => candidate.sessionId)
419
507
  .sort()
420
508
  .reverse();
421
509
  pending.push(...children);
@@ -527,9 +615,14 @@ export class FlexHarnessSessionDeletion<TScope> {
527
615
  const run = state.activeRuns.get(sessionId);
528
616
  if (run) this.core.runs.cancelRun(run, reason, context);
529
617
  }
530
- await Promise.allSettled([...groupIds]
531
- .map((sessionId) => state.sessionInitializations.get(sessionId))
532
- .filter((completion): completion is Promise<void> => completion !== undefined));
618
+ await Promise.allSettled([...groupIds].flatMap((sessionId) => {
619
+ const completions: Promise<unknown>[] = [];
620
+ const initialization = state.sessionInitializations.get(sessionId);
621
+ const hydration = state.sessionLoads.get(sessionId);
622
+ if (initialization) completions.push(initialization);
623
+ if (hydration) completions.push(hydration);
624
+ return completions;
625
+ }));
533
626
  for (const tombstone of group) {
534
627
  const sessionId = tombstone.sessionId;
535
628
  const retained = state.retainedSessionCleanups.get(sessionId);
@@ -595,6 +688,7 @@ export class FlexHarnessSessionDeletion<TScope> {
595
688
  'Tombstone cleanup requires its exact scope context before deleting projection data.',
596
689
  );
597
690
  }
691
+ if (!retained) await this.setDeletionRecoveryRequired(state, sessionId, true);
598
692
  await this.core.reversions.releaseDeletedSessionReversions(
599
693
  state,
600
694
  state.storageKey,
@@ -607,6 +701,10 @@ export class FlexHarnessSessionDeletion<TScope> {
607
701
  if (retained) retained.domainsCompleted = true;
608
702
  }
609
703
  }
704
+ // Domains and reversion references are durably resolved. Clear the redundant sidecar bit
705
+ // while the durable tombstone still prevents reuse and remains a recovery owner on a crash.
706
+ // Removing the tombstone first would leave an unresolvable orphan bit if its clear failed.
707
+ for (const tombstone of group) await this.setDeletionRecoveryRequired(state, tombstone.sessionId, false);
610
708
  await this.core.mutateScope(state, () => {
611
709
  for (const tombstone of group) {
612
710
  state.tombstones.delete(tombstone.sessionId);
@@ -614,4 +712,22 @@ export class FlexHarnessSessionDeletion<TScope> {
614
712
  }
615
713
  }, true);
616
714
  }
715
+
716
+ private async setDeletionRecoveryRequired(
717
+ state: IStorageState,
718
+ sessionId: string,
719
+ required: boolean,
720
+ ): Promise<void> {
721
+ if (!state.sessionLocal) return;
722
+ if (!state.qualifyingLegacy) {
723
+ try {
724
+ await this.core.stores.scopes.sessionLocal!.setRecoveryRequired(state.storageKey, sessionId, required);
725
+ } catch (error) {
726
+ state.lifecycle = 'fenced';
727
+ throw error;
728
+ }
729
+ }
730
+ if (required) state.recoverySessionIds.add(sessionId);
731
+ else state.recoverySessionIds.delete(sessionId);
732
+ }
617
733
  }
@@ -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);