@modelprofile.com/flexharness 18.1.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 (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 +122 -40
  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 +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/index.d.ts +1 -0
  29. package/dist_ts/index.js +2 -1
  30. package/dist_ts/interfaces.d.ts +84 -0
  31. package/dist_ts/interfaces.flexharness.d.ts +36 -0
  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 +42 -4
  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 +161 -52
  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 +290 -0
  60. package/ts/classes.stores.ts +150 -16
  61. package/ts/index.ts +2 -0
  62. package/ts/interfaces.flexharness.ts +38 -0
  63. package/ts/interfaces.ts +89 -0
  64. package/ts/readme.md +42 -4
  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
@@ -147,6 +147,13 @@ export class FlexHarnessRuns<TScope> {
147
147
  stepPartIds: new Set(),
148
148
  stepStreamedCalls: new Map(),
149
149
  stepInvalidCalls: new Map(),
150
+ checkpoint: {
151
+ committedPartIds: new Set(),
152
+ dirty: false,
153
+ outstanding: false,
154
+ saveMs: 0,
155
+ closed: false,
156
+ },
150
157
  textPartClosed: false,
151
158
  toolPartIds: new Map(),
152
159
  trustedToolExecutionErrors: new Map(),
@@ -267,12 +274,15 @@ export class FlexHarnessRuns<TScope> {
267
274
  }
268
275
  } finally {
269
276
  run.callbacksClosed = true;
277
+ this.core.callbacks.closeCheckpoint(run);
270
278
  this.core.permissions.rejectRunPermissions(
271
279
  run.state,
272
280
  run,
273
281
  run.ownerCancellation ?? new FlexHarnessAbortError('The run ended before permission was resolved.'),
274
282
  );
275
283
  if (run.state.activeRuns.get(run.sessionId) === run) run.state.activeRuns.delete(run.sessionId);
284
+ // After the run's outcome: a failed obligation update fences, it never replaces the result.
285
+ if (run.state.sessionLocal) await this.core.settleRecoveryObligation(run.state, run.stored);
276
286
  }
277
287
  }
278
288
 
@@ -282,6 +292,7 @@ export class FlexHarnessRuns<TScope> {
282
292
  generated: boolean,
283
293
  ): Promise<never> {
284
294
  run.callbacksClosed = true;
295
+ this.core.callbacks.closeCheckpoint(run);
285
296
  run.phase = 'closing';
286
297
  const cancelled = run.ownerCancellation !== undefined && run.internalFailure === undefined;
287
298
  const safeError = cancelled
@@ -852,6 +863,8 @@ export class FlexHarnessRuns<TScope> {
852
863
  }
853
864
  : undefined;
854
865
  const closePublication = this.core.openPublication(run.state, run.sessionId);
866
+ // The split saves every part of the answer so far; the next answer has none committed yet.
867
+ this.core.callbacks.resetCheckpoint(run);
855
868
  try {
856
869
  await this.core.mutateProjection(run.state, run.stored, () => {
857
870
  const index = run.stored.messages.findIndex((message) => message.messageId === answeredAssistantId);
@@ -874,7 +887,7 @@ export class FlexHarnessRuns<TScope> {
874
887
  cloneSerializable(steerMessage),
875
888
  cloneSerializable(nextAssistant),
876
889
  );
877
- });
890
+ }, false, (startedAt, completedAt) => this.core.callbacks.setCheckpointReference(run, startedAt, completedAt));
878
891
  if (completedAssistant && nextAssistant) {
879
892
  run.assistantMessageId = nextAssistant.messageId;
880
893
  run.reservedAssistantMessage = publicSnapshot(nextAssistant);
@@ -922,6 +935,8 @@ export class FlexHarnessRuns<TScope> {
922
935
  result?: IRunResultProjection,
923
936
  error?: Error,
924
937
  ): IFlexTerminalProjection {
938
+ // The terminal holds every part of the run: no checkpoint starts after it is built.
939
+ this.core.callbacks.closeCheckpoint(run);
925
940
  const timestamp = new Date().toISOString();
926
941
  const userMessage = run.continuation ? undefined : cloneSerializable(
927
942
  run.reservedUserMessage
@@ -76,7 +76,8 @@ export class FlexHarnessSessions<TScope> {
76
76
  constructor(private readonly core: FlexHarnessCore<TScope>) {}
77
77
 
78
78
  public async listSessions(scopeId: string): Promise<IFlexSession[]> {
79
- const { state } = await this.core.resolveState(scopeId);
79
+ const { scope, state } = await this.core.resolveState(scopeId);
80
+ await this.core.hydrateAllSessions(state, scopeId, scope.scope);
80
81
  await state.scopeQueue;
81
82
  this.core.assertOpen();
82
83
  this.core.assertStateAcceptingWork(state);
@@ -90,7 +91,7 @@ export class FlexHarnessSessions<TScope> {
90
91
  * The identities of a scope's live sessions, sorted by session id. Until the scope's load has
91
92
  * settled they are read from its stored scope snapshot, normalized as the load normalizes it:
92
93
  * they neither wait for the load nor read a session's projection, events or jobs, and nothing
93
- * changes a scope before its load settles. Once it has, they are its loaded sessions'.
94
+ * changes a scope before its load settles. Once it has, they are its complete catalogue's.
94
95
  */
95
96
  public async listSessionIdentities(scopeId: string): Promise<IFlexSessionIdentity[]> {
96
97
  return this.core.withScopeAdmission(scopeId, async (scope, admitted) => {
@@ -100,9 +101,8 @@ export class FlexHarnessSessions<TScope> {
100
101
  await state.scopeQueue;
101
102
  this.core.assertOpen();
102
103
  this.core.assertStateAcceptingWork(state);
103
- return sessionIdentities([...state.sessions.values()]
104
- .filter((stored) => !state.initializingSessions.has(stored.session.sessionId))
105
- .map((stored) => stored.session));
104
+ return sessionIdentities([...state.catalogue.values()]
105
+ .filter((session) => !state.initializingSessions.has(session.sessionId)));
106
106
  }
107
107
  const { snapshot } = normalizeScopeSnapshot(
108
108
  scope.storageKey,
@@ -150,7 +150,7 @@ export class FlexHarnessSessions<TScope> {
150
150
  }
151
151
  await resolved.state.scopeQueue;
152
152
  if (
153
- resolved.state.sessions.has(sessionId)
153
+ resolved.state.catalogue.has(sessionId)
154
154
  || resolved.state.tombstones.has(sessionId)
155
155
  || resolved.state.initializingSessions.has(sessionId)
156
156
  ) {
@@ -175,7 +175,7 @@ export class FlexHarnessSessions<TScope> {
175
175
  let metadata!: IFlexSession;
176
176
  try {
177
177
  await this.core.mutateScope(resolved.state, () => {
178
- if (resolved.state.sessions.has(sessionId) || resolved.state.tombstones.has(sessionId)) {
178
+ if (resolved.state.catalogue.has(sessionId) || resolved.state.tombstones.has(sessionId)) {
179
179
  throw new FlexHarnessValidationError(`Session "${sessionId}" already exists or is being deleted.`);
180
180
  }
181
181
  const timestamp = new Date().toISOString();
@@ -230,7 +230,7 @@ export class FlexHarnessSessions<TScope> {
230
230
  sessionId,
231
231
  'session-create',
232
232
  );
233
- scopeReserved ||= resolved.state.sessions.has(sessionId);
233
+ scopeReserved ||= resolved.state.catalogue.has(sessionId);
234
234
  if (!scopeReserved) throw projectedError;
235
235
  const tombstone: IFlexSessionTombstone = {
236
236
  sessionId,
@@ -295,7 +295,7 @@ export class FlexHarnessSessions<TScope> {
295
295
  }
296
296
 
297
297
  public async getSession(scopeId: string, sessionId: string): Promise<IFlexSession> {
298
- const { state } = await this.core.resolveState(scopeId);
298
+ const { state } = await this.core.resolveState(scopeId, sessionId);
299
299
  // Waits for the queued changes of this session only, never for another session's save.
300
300
  await this.core.sessionReadBarrier(state, sessionId);
301
301
  this.core.assertStateAcceptingWork(state);
@@ -303,7 +303,7 @@ export class FlexHarnessSessions<TScope> {
303
303
  }
304
304
 
305
305
  public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
306
- const { state } = await this.core.resolveState(scopeId);
306
+ const { state } = await this.core.resolveState(scopeId, sessionId);
307
307
  const stored = this.core.requireSession(state, sessionId);
308
308
  await stored.projectionQueue;
309
309
  this.core.assertStateAcceptingWork(state);
@@ -317,7 +317,7 @@ export class FlexHarnessSessions<TScope> {
317
317
  options: IFlexUpdateSessionOptions,
318
318
  ): Promise<IFlexSession> {
319
319
  validateUpdateSessionOptions(options, this.core.agentSessionPolicy.contextCompactor !== undefined);
320
- const { state } = await this.core.resolveState(scopeId);
320
+ const { state } = await this.core.resolveState(scopeId, sessionId);
321
321
  let result!: IFlexSession;
322
322
  await this.core.mutateSessionScope(state, sessionId, () => {
323
323
  const stored = Object.prototype.hasOwnProperty.call(options, 'archived')
@@ -347,7 +347,7 @@ export class FlexHarnessSessions<TScope> {
347
347
  options: IFlexMessageReadOptions = {},
348
348
  ): Promise<IFlexSessionView> {
349
349
  const includeUndone = readIncludeUndone(options, 'Session view options');
350
- const { state } = await this.core.resolveState(scopeId);
350
+ const { state } = await this.core.resolveState(scopeId, sessionId);
351
351
  let stored = this.core.requireSession(state, sessionId);
352
352
  for (let pass = 0; ; pass++) {
353
353
  if (pass === maxSessionViewPasses) {
@@ -392,7 +392,7 @@ export class FlexHarnessSessions<TScope> {
392
392
  options: IFlexMessageReadOptions = {},
393
393
  ): Promise<IFlexMessage[]> {
394
394
  const includeUndone = readIncludeUndone(options, 'Message read options');
395
- const { state } = await this.core.resolveState(scopeId);
395
+ const { state } = await this.core.resolveState(scopeId, sessionId);
396
396
  const stored = this.core.requireSession(state, sessionId);
397
397
  await stored.projectionQueue;
398
398
  this.core.assertStateAcceptingWork(state);
@@ -448,7 +448,7 @@ export class FlexHarnessSessions<TScope> {
448
448
  ) {
449
449
  throw new FlexHarnessValidationError('Message page cursor is invalid.');
450
450
  }
451
- const { state } = await this.core.resolveState(scopeId);
451
+ const { state } = await this.core.resolveState(scopeId, sessionId);
452
452
  const stored = this.core.requireSession(state, sessionId);
453
453
  await stored.projectionQueue;
454
454
  this.core.assertStateAcceptingWork(state);
@@ -503,7 +503,7 @@ export class FlexHarnessSessions<TScope> {
503
503
  const includeUndone = readIncludeUndone(options, 'Message read options');
504
504
  validateIdentifier(messageId, 'messageId');
505
505
  requireTransferIdentifier(messageId, 'messageId');
506
- const { state } = await this.core.resolveState(scopeId);
506
+ const { state } = await this.core.resolveState(scopeId, sessionId);
507
507
  const stored = this.core.requireSession(state, sessionId);
508
508
  await stored.projectionQueue;
509
509
  this.core.assertStateAcceptingWork(state);
@@ -516,7 +516,7 @@ export class FlexHarnessSessions<TScope> {
516
516
  event: IJsonObject & { type: string },
517
517
  ): Promise<void> {
518
518
  this.core.validateRuntimeEvent(event);
519
- const { scope, state } = await this.core.resolveState(scopeId);
519
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
520
520
  const stored = this.core.requireSession(state, sessionId);
521
521
  this.core.assertSessionWritable(stored);
522
522
  this.core.assertStateAcceptingWork(state);
@@ -539,7 +539,7 @@ export class FlexHarnessSessions<TScope> {
539
539
  validateIdentifier(compactionEventId, 'compactionEventId');
540
540
  requireTransferIdentifier(compactionEventId, 'compactionEventId');
541
541
  }
542
- const { scope, state } = await this.core.resolveState(scopeId);
542
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
543
543
  const stored = this.core.requireSession(state, sessionId);
544
544
  this.core.assertSessionWritable(stored);
545
545
  this.core.assertStateAcceptingWork(state);
@@ -58,7 +58,7 @@ export class FlexHarnessSlashCommands<TScope> {
58
58
  scopeId: string,
59
59
  sessionId: string,
60
60
  ): Promise<IFlexSlashCommandDescriptor[]> {
61
- const { scope, state } = await this.core.resolveState(scopeId);
61
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
62
62
  return this.trackSlashCommandListing(scopeId, state, sessionId, async (signal) => {
63
63
  await this.core.reversions.awaitReversionOperation(state.scopeQueue, signal);
64
64
  signal.throwIfAborted();
@@ -243,7 +243,7 @@ export class FlexHarnessSlashCommands<TScope> {
243
243
  });
244
244
  }
245
245
  const promptOptions = validateSlashCommandExecutionOptions(options);
246
- const { scope, state } = await this.core.resolveState(scopeId);
246
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
247
247
  await state.scopeQueue;
248
248
  this.core.assertOpen();
249
249
  this.core.assertStateAcceptingWork(state);
@@ -200,7 +200,7 @@ export class FlexHarnessSubagents<TScope> {
200
200
  scopeId: string,
201
201
  sessionId: string,
202
202
  ): Promise<IFlexBackgroundExecution[]> {
203
- const { state } = await this.core.resolveState(scopeId);
203
+ const { state } = await this.core.resolveState(scopeId, sessionId);
204
204
  const stored = this.core.requireSession(state, sessionId);
205
205
  this.core.assertStateAcceptingWork(state);
206
206
  if (!stored.jobs) return [];
@@ -222,7 +222,7 @@ export class FlexHarnessSubagents<TScope> {
222
222
  ): Promise<IFlexBackgroundExecution> {
223
223
  validateIdentifier(executionId, 'executionId');
224
224
  requireTransferIdentifier(executionId, 'executionId');
225
- const { state } = await this.core.resolveState(scopeId);
225
+ const { state } = await this.core.resolveState(scopeId, sessionId);
226
226
  const stored = this.core.requireSession(state, sessionId);
227
227
  this.core.assertStateAcceptingWork(state);
228
228
  try {
@@ -241,7 +241,7 @@ export class FlexHarnessSubagents<TScope> {
241
241
  ): Promise<void> {
242
242
  validateIdentifier(executionId, 'executionId');
243
243
  requireTransferIdentifier(executionId, 'executionId');
244
- const { scope, state } = await this.core.resolveState(scopeId);
244
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
245
245
  const stored = this.core.requireSession(state, sessionId);
246
246
  this.core.assertStateAcceptingWork(state);
247
247
  try {
@@ -286,7 +286,7 @@ export class FlexHarnessSubagents<TScope> {
286
286
  || session.agent === undefined
287
287
  || session.depth === undefined
288
288
  ) throw new FlexHarnessValidationError('Subagent session provenance is incomplete.');
289
- const parent = state.sessions.get(session.parentSessionId)?.session
289
+ const parent = state.catalogue.get(session.parentSessionId)
290
290
  ?? state.tombstones.get(session.parentSessionId);
291
291
  if (!parent) {
292
292
  throw new FlexHarnessValidationError(
@@ -553,8 +553,14 @@ export class FlexHarnessSubagents<TScope> {
553
553
  waitMs: plugins.z.number().int().min(0).max(240_000).optional(),
554
554
  }).strict(),
555
555
  execute: async ({ taskId, waitMs = 0 }: { taskId: string; waitMs?: number }) => {
556
- const child = run.state.sessions.get(taskId);
557
- if (!child || run.state.tombstones.has(taskId) || child.session.parentSessionId !== run.sessionId
556
+ const metadata = run.state.catalogue.get(taskId);
557
+ if (!metadata || run.state.tombstones.has(taskId) || metadata.parentSessionId !== run.sessionId
558
+ || metadata.configurationRef !== run.stored.session.configurationRef) {
559
+ throw new FlexHarnessValidationError('The task is not owned by this parent and configuration.');
560
+ }
561
+ const child = await this.core.hydrateSession(run.state, taskId, run.scopeId, run.scope as TScope);
562
+ if (run.state.sessions.get(taskId) !== child || run.state.tombstones.has(taskId)
563
+ || child.session.parentSessionId !== run.sessionId
558
564
  || child.session.configurationRef !== run.stored.session.configurationRef) {
559
565
  throw new FlexHarnessValidationError('The task is not owned by this parent and configuration.');
560
566
  }
@@ -620,6 +626,20 @@ export class FlexHarnessSubagents<TScope> {
620
626
  resolveInitialization?.();
621
627
  };
622
628
  try {
629
+ // Hydration can queue repairs; it must finish before acquiring the scope mutation lane.
630
+ const existingMetadata = state.catalogue.get(sessionId);
631
+ if (existingMetadata) {
632
+ if (
633
+ existingMetadata.parentSessionId !== run.sessionId
634
+ || existingMetadata.agent !== definition.name
635
+ || existingMetadata.configurationRef !== run.stored.session.configurationRef
636
+ ) {
637
+ throw new FlexHarnessValidationError(
638
+ `Task session "${sessionId}" is not owned by this parent, agent, and configuration.`,
639
+ );
640
+ }
641
+ await this.core.hydrateSession(state, sessionId, run.scopeId, run.scope as TScope);
642
+ }
623
643
  await this.core.mutateScope(state, () => {
624
644
  if (state.sessions.get(run.sessionId) !== run.stored || state.tombstones.has(run.sessionId)) {
625
645
  throw new FlexHarnessAbortError('The parent session no longer owns this subagent request.');
@@ -641,15 +661,19 @@ export class FlexHarnessSubagents<TScope> {
641
661
  }
642
662
  visited.add(ancestor.sessionId);
643
663
  ancestor = ancestor.parentSessionId
644
- ? state.sessions.get(ancestor.parentSessionId)?.session
664
+ ? state.catalogue.get(ancestor.parentSessionId)
645
665
  : undefined;
646
666
  }
667
+ const existingSession = state.catalogue.get(sessionId);
647
668
  const existing = state.sessions.get(sessionId);
648
- if (existing) {
669
+ if (existingSession) {
670
+ if (!existing) {
671
+ throw new FlexHarnessAbortError('The child session lost its hydrated runtime ownership.');
672
+ }
649
673
  if (
650
- existing.session.parentSessionId !== run.sessionId
651
- || existing.session.agent !== definition.name
652
- || existing.session.configurationRef !== run.stored.session.configurationRef
674
+ existingSession.parentSessionId !== run.sessionId
675
+ || existingSession.agent !== definition.name
676
+ || existingSession.configurationRef !== run.stored.session.configurationRef
653
677
  ) {
654
678
  throw new FlexHarnessValidationError(
655
679
  `Task session "${sessionId}" is not owned by this parent, agent, and configuration.`,
@@ -657,8 +681,8 @@ export class FlexHarnessSubagents<TScope> {
657
681
  }
658
682
  if (
659
683
  taskId === undefined
660
- && (existing.session.parentRunId !== run.runId
661
- || existing.session.parentToolCallId !== toolCallId)
684
+ && (existingSession.parentRunId !== run.runId
685
+ || existingSession.parentToolCallId !== toolCallId)
662
686
  ) {
663
687
  throw new FlexHarnessValidationError(
664
688
  `Subagent task "${sessionId}" does not match its deterministic invocation origin.`,
@@ -672,10 +696,10 @@ export class FlexHarnessSubagents<TScope> {
672
696
  `Subagent task "${sessionId}" has an uncertain prior execution and cannot be replayed automatically.`,
673
697
  );
674
698
  }
675
- if (state.activeRuns.has(sessionId) || existing.session.status !== 'idle') {
699
+ if (state.activeRuns.has(sessionId) || existingSession.status !== 'idle') {
676
700
  throw new FlexHarnessSessionBusyError(sessionId, 'cannot be resumed while it is not idle');
677
701
  }
678
- if (taskId !== undefined && existing.session.parentRunId === run.runId) {
702
+ if (taskId !== undefined && existingSession.parentRunId === run.runId) {
679
703
  throw new FlexHarnessValidationError('taskId can only resume a child from a later parent run.');
680
704
  }
681
705
  placeholder = existing;
@@ -746,6 +770,7 @@ export class FlexHarnessSubagents<TScope> {
746
770
  throw aborted;
747
771
  }
748
772
  state.sessions.set(sessionId, loaded);
773
+ state.catalogue.set(sessionId, loaded.session);
749
774
  this.core.emitEvent(run.scopeId, metadata, {
750
775
  type: 'session.created',
751
776
  session: publicSnapshot(metadata),
@@ -40,7 +40,7 @@ export class FlexHarnessToolDispatch<TScope> {
40
40
  scopeId: string,
41
41
  sessionId: string,
42
42
  ): Promise<IFlexUncertainToolExecution[]> {
43
- const { state } = await this.core.resolveState(scopeId);
43
+ const { state } = await this.core.resolveState(scopeId, sessionId);
44
44
  const stored = this.core.requireSession(state, sessionId);
45
45
  this.core.assertStateAcceptingWork(state);
46
46
  try {
@@ -68,7 +68,7 @@ export class FlexHarnessToolDispatch<TScope> {
68
68
  if (!reconciliation || typeof reconciliation !== 'object' || Array.isArray(reconciliation)) {
69
69
  throw new FlexHarnessValidationError('Tool execution reconciliation must be a plain object.');
70
70
  }
71
- const { scope, state } = await this.core.resolveState(scopeId);
71
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
72
72
  const stored = this.core.requireSession(state, sessionId);
73
73
  this.core.assertSessionWritable(stored);
74
74
  this.core.assertStateAcceptingWork(state);
@@ -70,6 +70,19 @@ export class FlexHarness<TScope = unknown> {
70
70
  this.core = new FlexHarnessCore<TScope>(options);
71
71
  }
72
72
 
73
+ /** Explicit startup recovery; legacy qualification is never an implicit request fallback. */
74
+ public prepareScope(
75
+ scopeId: string,
76
+ options: import('./interfaces.js').IFlexPrepareScopeOptions = {},
77
+ ): Promise<import('./interfaces.js').IFlexScopeCatalogue> {
78
+ return this.core.prepareScope(scopeId, options);
79
+ }
80
+
81
+ /** Complete live metadata without hydrating unrelated session histories. */
82
+ public getScopeCatalogue(scopeId: string): Promise<import('./interfaces.js').IFlexScopeCatalogue> {
83
+ return this.core.getScopeCatalogue(scopeId);
84
+ }
85
+
73
86
  public listSessions(scopeId: string): Promise<IFlexSession[]> {
74
87
  return this.core.sessions.listSessions(scopeId);
75
88
  }
@@ -0,0 +1,290 @@
1
+ import * as plugins from './plugins.js';
2
+ import {
3
+ FlexHarnessStoreCommitUncertainError,
4
+ FlexHarnessStoreConflictError,
5
+ FlexHarnessStoreFormatError,
6
+ FlexHarnessValidationError,
7
+ } from './errors.js';
8
+ import type {
9
+ IFlexScopeRecoverySnapshot,
10
+ IFlexScopeRecoveryStore,
11
+ IFlexScopeSnapshot,
12
+ IFlexScopeStore,
13
+ IFlexSessionLocalScopeStore,
14
+ } from './interfaces.js';
15
+ import {
16
+ assertFlexScopeSnapshot,
17
+ assertJsonSerializable,
18
+ cloneSerializable,
19
+ } from './utils.json.js';
20
+ import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
21
+ import {
22
+ validateExpectedRevision,
23
+ validateIdentifier,
24
+ validateSnapshotSave,
25
+ } from './utils.storerules.js';
26
+
27
+ function assertRecoverySessionIds(value: unknown): asserts value is string[] {
28
+ if (
29
+ !Array.isArray(value)
30
+ || value.some((id) => typeof id !== 'string' || !id.trim())
31
+ || new Set(value).size !== value.length
32
+ ) {
33
+ throw new FlexHarnessStoreFormatError('recoverySessionIds must contain unique non-empty string ids.');
34
+ }
35
+ }
36
+
37
+ /** Strict sidecar validation shared by recovery-store adapters; scope snapshots stay schema 1. */
38
+ export function assertFlexScopeRecoverySnapshot(
39
+ value: unknown,
40
+ ): asserts value is IFlexScopeRecoverySnapshot {
41
+ assertJsonSerializable(value, '$scopeRecovery');
42
+ assertRecord(value, '$scopeRecovery');
43
+ assertExactKeys(value, [
44
+ 'schemaVersion', 'revision', 'catalogueRevision', 'catalogueDigest', 'recoverySessionIds',
45
+ ], '$scopeRecovery');
46
+ if (value.schemaVersion !== 1) {
47
+ throw new FlexHarnessStoreFormatError('Scope recovery schemaVersion must be 1.');
48
+ }
49
+ for (const key of ['revision', 'catalogueRevision'] as const) {
50
+ if (!Number.isSafeInteger(value[key]) || Number(value[key]) < 0) {
51
+ throw new FlexHarnessStoreFormatError(`Scope recovery ${key} must be a non-negative safe integer.`);
52
+ }
53
+ }
54
+ if (typeof value.catalogueDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.catalogueDigest)) {
55
+ throw new FlexHarnessStoreFormatError('Scope recovery catalogueDigest must be a lowercase SHA-256 digest.');
56
+ }
57
+ assertRecoverySessionIds(value.recoverySessionIds);
58
+ }
59
+
60
+ /** Checks the sidecar CAS admission rule and copies the caller-owned value before a backend awaits. */
61
+ export function validateFlexScopeRecoverySave(
62
+ snapshot: IFlexScopeRecoverySnapshot,
63
+ expectedRevision: number,
64
+ ): IFlexScopeRecoverySnapshot {
65
+ assertFlexScopeRecoverySnapshot(snapshot);
66
+ validateExpectedRevision(expectedRevision);
67
+ if (snapshot.revision !== expectedRevision + 1) {
68
+ throw new FlexHarnessStoreFormatError(
69
+ `Scope recovery revision ${snapshot.revision} must equal expected revision ${expectedRevision} plus one.`,
70
+ );
71
+ }
72
+ return cloneSerializable(snapshot);
73
+ }
74
+
75
+ function canonicalCatalogueJson(value: unknown): string {
76
+ if (Array.isArray(value)) return `[${value.map(canonicalCatalogueJson).join(',')}]`;
77
+ if (value !== null && typeof value === 'object') {
78
+ const fields = value as Record<string, unknown>;
79
+ return `{${Object.keys(fields).sort().map((key) =>
80
+ `${JSON.stringify(key)}:${canonicalCatalogueJson(fields[key])}`,
81
+ ).join(',')}}`;
82
+ }
83
+ const serialized = JSON.stringify(value);
84
+ if (serialized === undefined) {
85
+ throw new FlexHarnessStoreFormatError('Scope catalogue is not canonical JSON.');
86
+ }
87
+ return serialized;
88
+ }
89
+
90
+ function catalogueDigest(snapshot: IFlexScopeSnapshot | undefined): string {
91
+ const canonical = canonicalCatalogueJson({
92
+ catalogueRevision: snapshot?.revision ?? 0,
93
+ snapshot: snapshot ?? null,
94
+ });
95
+ return plugins.crypto.createHash('sha256').update(canonical).digest('hex');
96
+ }
97
+
98
+ interface IRecoveryEvidence {
99
+ snapshot: IFlexScopeSnapshot | undefined;
100
+ recovery: IFlexScopeRecoverySnapshot | undefined;
101
+ qualified: boolean;
102
+ }
103
+
104
+ /**
105
+ * Adds session-local recovery to any durable scope CAS store without changing its snapshots.
106
+ *
107
+ * The host must exclusively own the namespace, including qualification and every legacy writer;
108
+ * there must be no simultaneous legacy writer, even through another wrapper/process. The helper
109
+ * lane serializes this sidecar adapter's operations per storage key, not distributed ownership.
110
+ * Clear an obligation only after the session effects/recovery are conclusively durable; an
111
+ * uncertain session operation must retain its obligation, never attempt a clear.
112
+ * Qualification requires both the snapshot proof and authoritative all-domain write provenance;
113
+ * a legacy projection/event/job write can invalidate provenance without changing the scope.
114
+ * Normal load/save keep the legacy contract: a legacy save leaves the old proof stale by revision.
115
+ * A catalogue save commits the scope first and its matching proof second, preserving obligations;
116
+ * a failure in that gap is CommitUncertain and never implicitly qualifies the resulting catalogue.
117
+ */
118
+ export class RecoverableFlexScopeStore implements IFlexScopeStore {
119
+ private static readonly lanes = new WeakMap<IFlexScopeRecoveryStore, Map<string, Promise<void>>>();
120
+
121
+ public readonly sessionLocal: IFlexSessionLocalScopeStore = {
122
+ releaseOwnership: (storageKey) => this.recoveryStore.deactivateWriteProvenance(storageKey),
123
+ loadCatalogue: (storageKey) => this.loadCatalogue(storageKey),
124
+ saveCatalogue: (storageKey, snapshot, expectedRevision) =>
125
+ this.saveCatalogue(storageKey, snapshot, expectedRevision),
126
+ setRecoveryRequired: (storageKey, sessionId, required) =>
127
+ this.setRecoveryRequired(storageKey, sessionId, required),
128
+ qualifyCatalogue: (storageKey, snapshot, recoverySessionIds) =>
129
+ this.qualifyCatalogue(storageKey, snapshot, recoverySessionIds),
130
+ };
131
+
132
+ constructor(
133
+ private readonly scopes: IFlexScopeStore,
134
+ private readonly recoveryStore: IFlexScopeRecoveryStore,
135
+ ) {}
136
+
137
+ private inLane<T>(storageKey: string, operation: () => Promise<T>): Promise<T> {
138
+ validateIdentifier(storageKey, 'storageKey');
139
+ let lanes = RecoverableFlexScopeStore.lanes.get(this.recoveryStore);
140
+ if (!lanes) {
141
+ lanes = new Map();
142
+ RecoverableFlexScopeStore.lanes.set(this.recoveryStore, lanes);
143
+ }
144
+ const result = (lanes.get(storageKey) ?? Promise.resolve()).then(operation);
145
+ const barrier = result.then(() => undefined, () => undefined);
146
+ lanes.set(storageKey, barrier);
147
+ void barrier.then(() => {
148
+ if (lanes.get(storageKey) === barrier) lanes.delete(storageKey);
149
+ });
150
+ return result;
151
+ }
152
+
153
+ public load(storageKey: string): Promise<IFlexScopeSnapshot | undefined> {
154
+ return this.scopes.load(storageKey);
155
+ }
156
+
157
+ public save(storageKey: string, snapshot: IFlexScopeSnapshot, expectedRevision: number): Promise<void> {
158
+ return this.inLane(storageKey, () => {
159
+ this.recoveryStore.deactivateWriteProvenance(storageKey);
160
+ return this.scopes.save(storageKey, snapshot, expectedRevision);
161
+ });
162
+ }
163
+
164
+ private async readEvidence(storageKey: string): Promise<IRecoveryEvidence> {
165
+ const provenance = await this.recoveryStore.loadWriteProvenance(storageKey);
166
+ const snapshot = await this.scopes.load(storageKey);
167
+ if (snapshot !== undefined) assertFlexScopeSnapshot(snapshot);
168
+ const recovery = await this.recoveryStore.load(storageKey);
169
+ if (recovery !== undefined) assertFlexScopeRecoverySnapshot(recovery);
170
+ const qualified = provenance && (recovery === undefined
171
+ ? snapshot === undefined
172
+ : recovery.catalogueRevision === (snapshot?.revision ?? 0)
173
+ && recovery.catalogueDigest === catalogueDigest(snapshot));
174
+ if (!qualified) this.recoveryStore.deactivateWriteProvenance(storageKey);
175
+ return {
176
+ snapshot: snapshot === undefined ? undefined : cloneSerializable(snapshot),
177
+ recovery: recovery === undefined ? undefined : cloneSerializable(recovery),
178
+ qualified,
179
+ };
180
+ }
181
+
182
+ private loadCatalogue(storageKey: string): ReturnType<IFlexSessionLocalScopeStore['loadCatalogue']> {
183
+ return this.inLane(storageKey, async () => {
184
+ const evidence = await this.readEvidence(storageKey);
185
+ return {
186
+ snapshot: evidence.snapshot,
187
+ qualified: evidence.qualified,
188
+ recoverySessionIds: evidence.recovery?.recoverySessionIds ?? [],
189
+ };
190
+ });
191
+ }
192
+
193
+ private assertQualified(storageKey: string, evidence: IRecoveryEvidence): void {
194
+ if (!evidence.qualified) {
195
+ throw new FlexHarnessStoreFormatError(
196
+ `Scope catalogue "${storageKey}" requires explicit qualification before catalogue writes or recovery clears.`,
197
+ );
198
+ }
199
+ }
200
+
201
+ private saveProof(
202
+ storageKey: string,
203
+ snapshot: IFlexScopeSnapshot | undefined,
204
+ recovery: IFlexScopeRecoverySnapshot | undefined,
205
+ recoverySessionIds: string[],
206
+ ): Promise<void> {
207
+ const expectedRevision = recovery?.revision ?? 0;
208
+ return this.recoveryStore.save(storageKey, {
209
+ schemaVersion: 1,
210
+ revision: expectedRevision + 1,
211
+ catalogueRevision: snapshot?.revision ?? 0,
212
+ catalogueDigest: catalogueDigest(snapshot),
213
+ recoverySessionIds,
214
+ }, expectedRevision);
215
+ }
216
+
217
+ private async saveCatalogue(
218
+ storageKey: string,
219
+ snapshot: IFlexScopeSnapshot,
220
+ expectedRevision: number,
221
+ ): Promise<void> {
222
+ const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexScopeSnapshot);
223
+ return this.inLane(storageKey, async () => {
224
+ const evidence = await this.readEvidence(storageKey);
225
+ this.assertQualified(storageKey, evidence);
226
+ await this.scopes.save(storageKey, validated, expectedRevision);
227
+ try {
228
+ await this.saveProof(
229
+ storageKey, validated, evidence.recovery, evidence.recovery?.recoverySessionIds ?? [],
230
+ );
231
+ } catch (cause) {
232
+ throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
233
+ }
234
+ });
235
+ }
236
+
237
+ private async setRecoveryRequired(storageKey: string, sessionId: string, required: boolean): Promise<void> {
238
+ validateIdentifier(sessionId, 'sessionId');
239
+ if (typeof required !== 'boolean') {
240
+ throw new FlexHarnessValidationError('required must be a boolean.');
241
+ }
242
+ return this.inLane(storageKey, async () => {
243
+ const evidence = await this.readEvidence(storageKey);
244
+ if (!required) this.assertQualified(storageKey, evidence);
245
+ const ids = evidence.recovery?.recoverySessionIds ?? [];
246
+ if (ids.includes(sessionId) === required) return;
247
+ const recoverySessionIds = required ? [...ids, sessionId] : ids.filter((id) => id !== sessionId);
248
+ if (evidence.qualified) {
249
+ await this.saveProof(storageKey, evidence.snapshot, evidence.recovery, recoverySessionIds);
250
+ } else {
251
+ // Adding an obligation is safe without qualification, but it must not create a proof of
252
+ // the unqualified snapshot. An absent proof remains the proof of an absent catalogue.
253
+ const expectedRevision = evidence.recovery?.revision ?? 0;
254
+ await this.recoveryStore.save(storageKey, {
255
+ schemaVersion: 1,
256
+ revision: expectedRevision + 1,
257
+ catalogueRevision: evidence.recovery?.catalogueRevision ?? 0,
258
+ catalogueDigest: evidence.recovery?.catalogueDigest ?? catalogueDigest(undefined),
259
+ recoverySessionIds,
260
+ }, expectedRevision);
261
+ }
262
+ });
263
+ }
264
+
265
+ private async qualifyCatalogue(
266
+ storageKey: string,
267
+ snapshot: IFlexScopeSnapshot,
268
+ recoverySessionIds: string[],
269
+ ): Promise<void> {
270
+ assertFlexScopeSnapshot(snapshot);
271
+ assertRecoverySessionIds(recoverySessionIds);
272
+ const validated = cloneSerializable(snapshot);
273
+ const ids = [...recoverySessionIds];
274
+ return this.inLane(storageKey, async () => {
275
+ const evidence = await this.readEvidence(storageKey);
276
+ if (evidence.snapshot === undefined || catalogueDigest(evidence.snapshot) !== catalogueDigest(validated)) {
277
+ throw new FlexHarnessStoreConflictError(storageKey, validated.revision, evidence.snapshot?.revision ?? 0);
278
+ }
279
+ // The exclusive owner supplies the complete unresolved set after canonical qualification.
280
+ // Publish the proof inactive: a crash/failure before witness qualification cannot bless it.
281
+ this.recoveryStore.deactivateWriteProvenance(storageKey);
282
+ try {
283
+ await this.saveProof(storageKey, validated, evidence.recovery, ids);
284
+ await this.recoveryStore.qualifyWriteProvenance(storageKey);
285
+ } catch (cause) {
286
+ throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
287
+ }
288
+ });
289
+ }
290
+ }