@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
@@ -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
@@ -14,6 +14,7 @@ import {
14
14
  type IFlexMessagePageOptions,
15
15
  type IFlexMessageReadOptions,
16
16
  type IFlexSession,
17
+ type IFlexSessionIdentity,
17
18
  type IFlexSessionView,
18
19
  type IFlexSessionMetrics,
19
20
  type IFlexSessionTombstone,
@@ -48,6 +49,7 @@ import {
48
49
  combineErrors,
49
50
  } from './utils.flexharness.js';
50
51
  import type { FlexHarnessCore } from './classes.flexharness.core.js';
52
+ import { liveScopeSessions, normalizeScopeSnapshot, sessionIdentities } from './utils.scopesnapshot.js';
51
53
 
52
54
  /**
53
55
  * Consecutive waits a session view makes for queued writes and open sections to settle. Each wait
@@ -74,7 +76,8 @@ export class FlexHarnessSessions<TScope> {
74
76
  constructor(private readonly core: FlexHarnessCore<TScope>) {}
75
77
 
76
78
  public async listSessions(scopeId: string): Promise<IFlexSession[]> {
77
- 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);
78
81
  await state.scopeQueue;
79
82
  this.core.assertOpen();
80
83
  this.core.assertStateAcceptingWork(state);
@@ -84,6 +87,33 @@ export class FlexHarnessSessions<TScope> {
84
87
  .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)));
85
88
  }
86
89
 
90
+ /**
91
+ * The identities of a scope's live sessions, sorted by session id. Until the scope's load has
92
+ * settled they are read from its stored scope snapshot, normalized as the load normalizes it:
93
+ * they neither wait for the load nor read a session's projection, events or jobs, and nothing
94
+ * changes a scope before its load settles. Once it has, they are its complete catalogue's.
95
+ */
96
+ public async listSessionIdentities(scopeId: string): Promise<IFlexSessionIdentity[]> {
97
+ return this.core.withScopeAdmission(scopeId, async (scope, admitted) => {
98
+ const stateLoad = this.core.stateLoads.get(scope.storageKey);
99
+ if (stateLoad && this.core.isStateLoaded(stateLoad)) {
100
+ const state = await this.core.admittedState(scopeId, scope, stateLoad, admitted);
101
+ await state.scopeQueue;
102
+ this.core.assertOpen();
103
+ this.core.assertStateAcceptingWork(state);
104
+ return sessionIdentities([...state.catalogue.values()]
105
+ .filter((session) => !state.initializingSessions.has(session.sessionId)));
106
+ }
107
+ const { snapshot } = normalizeScopeSnapshot(
108
+ scope.storageKey,
109
+ await this.core.stores.scopes.load(scope.storageKey),
110
+ );
111
+ this.core.assertOpen();
112
+ if (!admitted()) throw this.core.createScopeRetirementError();
113
+ return sessionIdentities(liveScopeSessions(snapshot));
114
+ });
115
+ }
116
+
87
117
  public async createSession(
88
118
  scopeId: string,
89
119
  options: IFlexCreateSessionOptions = {},
@@ -120,7 +150,7 @@ export class FlexHarnessSessions<TScope> {
120
150
  }
121
151
  await resolved.state.scopeQueue;
122
152
  if (
123
- resolved.state.sessions.has(sessionId)
153
+ resolved.state.catalogue.has(sessionId)
124
154
  || resolved.state.tombstones.has(sessionId)
125
155
  || resolved.state.initializingSessions.has(sessionId)
126
156
  ) {
@@ -145,7 +175,7 @@ export class FlexHarnessSessions<TScope> {
145
175
  let metadata!: IFlexSession;
146
176
  try {
147
177
  await this.core.mutateScope(resolved.state, () => {
148
- if (resolved.state.sessions.has(sessionId) || resolved.state.tombstones.has(sessionId)) {
178
+ if (resolved.state.catalogue.has(sessionId) || resolved.state.tombstones.has(sessionId)) {
149
179
  throw new FlexHarnessValidationError(`Session "${sessionId}" already exists or is being deleted.`);
150
180
  }
151
181
  const timestamp = new Date().toISOString();
@@ -200,7 +230,7 @@ export class FlexHarnessSessions<TScope> {
200
230
  sessionId,
201
231
  'session-create',
202
232
  );
203
- scopeReserved ||= resolved.state.sessions.has(sessionId);
233
+ scopeReserved ||= resolved.state.catalogue.has(sessionId);
204
234
  if (!scopeReserved) throw projectedError;
205
235
  const tombstone: IFlexSessionTombstone = {
206
236
  sessionId,
@@ -265,7 +295,7 @@ export class FlexHarnessSessions<TScope> {
265
295
  }
266
296
 
267
297
  public async getSession(scopeId: string, sessionId: string): Promise<IFlexSession> {
268
- const { state } = await this.core.resolveState(scopeId);
298
+ const { state } = await this.core.resolveState(scopeId, sessionId);
269
299
  // Waits for the queued changes of this session only, never for another session's save.
270
300
  await this.core.sessionReadBarrier(state, sessionId);
271
301
  this.core.assertStateAcceptingWork(state);
@@ -273,7 +303,7 @@ export class FlexHarnessSessions<TScope> {
273
303
  }
274
304
 
275
305
  public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
276
- const { state } = await this.core.resolveState(scopeId);
306
+ const { state } = await this.core.resolveState(scopeId, sessionId);
277
307
  const stored = this.core.requireSession(state, sessionId);
278
308
  await stored.projectionQueue;
279
309
  this.core.assertStateAcceptingWork(state);
@@ -287,7 +317,7 @@ export class FlexHarnessSessions<TScope> {
287
317
  options: IFlexUpdateSessionOptions,
288
318
  ): Promise<IFlexSession> {
289
319
  validateUpdateSessionOptions(options, this.core.agentSessionPolicy.contextCompactor !== undefined);
290
- const { state } = await this.core.resolveState(scopeId);
320
+ const { state } = await this.core.resolveState(scopeId, sessionId);
291
321
  let result!: IFlexSession;
292
322
  await this.core.mutateSessionScope(state, sessionId, () => {
293
323
  const stored = Object.prototype.hasOwnProperty.call(options, 'archived')
@@ -317,7 +347,7 @@ export class FlexHarnessSessions<TScope> {
317
347
  options: IFlexMessageReadOptions = {},
318
348
  ): Promise<IFlexSessionView> {
319
349
  const includeUndone = readIncludeUndone(options, 'Session view options');
320
- const { state } = await this.core.resolveState(scopeId);
350
+ const { state } = await this.core.resolveState(scopeId, sessionId);
321
351
  let stored = this.core.requireSession(state, sessionId);
322
352
  for (let pass = 0; ; pass++) {
323
353
  if (pass === maxSessionViewPasses) {
@@ -362,7 +392,7 @@ export class FlexHarnessSessions<TScope> {
362
392
  options: IFlexMessageReadOptions = {},
363
393
  ): Promise<IFlexMessage[]> {
364
394
  const includeUndone = readIncludeUndone(options, 'Message read options');
365
- const { state } = await this.core.resolveState(scopeId);
395
+ const { state } = await this.core.resolveState(scopeId, sessionId);
366
396
  const stored = this.core.requireSession(state, sessionId);
367
397
  await stored.projectionQueue;
368
398
  this.core.assertStateAcceptingWork(state);
@@ -418,7 +448,7 @@ export class FlexHarnessSessions<TScope> {
418
448
  ) {
419
449
  throw new FlexHarnessValidationError('Message page cursor is invalid.');
420
450
  }
421
- const { state } = await this.core.resolveState(scopeId);
451
+ const { state } = await this.core.resolveState(scopeId, sessionId);
422
452
  const stored = this.core.requireSession(state, sessionId);
423
453
  await stored.projectionQueue;
424
454
  this.core.assertStateAcceptingWork(state);
@@ -473,7 +503,7 @@ export class FlexHarnessSessions<TScope> {
473
503
  const includeUndone = readIncludeUndone(options, 'Message read options');
474
504
  validateIdentifier(messageId, 'messageId');
475
505
  requireTransferIdentifier(messageId, 'messageId');
476
- const { state } = await this.core.resolveState(scopeId);
506
+ const { state } = await this.core.resolveState(scopeId, sessionId);
477
507
  const stored = this.core.requireSession(state, sessionId);
478
508
  await stored.projectionQueue;
479
509
  this.core.assertStateAcceptingWork(state);
@@ -486,7 +516,7 @@ export class FlexHarnessSessions<TScope> {
486
516
  event: IJsonObject & { type: string },
487
517
  ): Promise<void> {
488
518
  this.core.validateRuntimeEvent(event);
489
- const { scope, state } = await this.core.resolveState(scopeId);
519
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
490
520
  const stored = this.core.requireSession(state, sessionId);
491
521
  this.core.assertSessionWritable(stored);
492
522
  this.core.assertStateAcceptingWork(state);
@@ -509,7 +539,7 @@ export class FlexHarnessSessions<TScope> {
509
539
  validateIdentifier(compactionEventId, 'compactionEventId');
510
540
  requireTransferIdentifier(compactionEventId, 'compactionEventId');
511
541
  }
512
- const { scope, state } = await this.core.resolveState(scopeId);
542
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
513
543
  const stored = this.core.requireSession(state, sessionId);
514
544
  this.core.assertSessionWritable(stored);
515
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);
@@ -35,6 +35,7 @@ import type {
35
35
  IFlexScheduledPromptAdmission,
36
36
  IFlexSchedulePromptOptions,
37
37
  IFlexSession,
38
+ IFlexSessionIdentity,
38
39
  IFlexSessionView,
39
40
  IFlexSessionMetrics,
40
41
  IFlexSessionImportHandle,
@@ -69,10 +70,31 @@ export class FlexHarness<TScope = unknown> {
69
70
  this.core = new FlexHarnessCore<TScope>(options);
70
71
  }
71
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
+
72
86
  public listSessions(scopeId: string): Promise<IFlexSession[]> {
73
87
  return this.core.sessions.listSessions(scopeId);
74
88
  }
75
89
 
90
+ /**
91
+ * The identities of a scope's live sessions, sorted by session id. Before the scope is loaded
92
+ * they come from its stored scope metadata alone, without loading any session.
93
+ */
94
+ public listSessionIdentities(scopeId: string): Promise<IFlexSessionIdentity[]> {
95
+ return this.core.sessions.listSessionIdentities(scopeId);
96
+ }
97
+
76
98
  public createSession(
77
99
  scopeId: string,
78
100
  options?: IFlexCreateSessionOptions,