@modelprofile.com/flexharness 18.6.0 → 18.8.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.
@@ -1,5 +1,10 @@
1
1
  import * as plugins from './plugins.js';
2
- import { FlexHarnessValidationError } from './errors.js';
2
+ import {
3
+ FlexHarnessAbortError,
4
+ FlexHarnessUncertainToolCursorStaleError,
5
+ FlexHarnessUncertainToolInspectionStaleError,
6
+ FlexHarnessValidationError,
7
+ } from './errors.js';
3
8
  import {
4
9
  FLEX_CODE_MODE_TOOL_NAME,
5
10
  FLEX_RESULT_METHOD,
@@ -10,6 +15,10 @@ import {
10
15
  type IFlexCatalogSearchInput,
11
16
  type IFlexToolProviderContext,
12
17
  type IFlexUncertainToolExecution,
18
+ type IFlexUncertainToolExecutionPage,
19
+ type IFlexUncertainToolExecutionPageOptions,
20
+ type IFlexSessionGeneration,
21
+ type TFlexUncertainToolExecutionMetadata,
13
22
  type TFlexAgentToolSet,
14
23
  type TFlexToolExecutionReconciliation,
15
24
  type TJsonValue,
@@ -25,7 +34,7 @@ import {
25
34
  } from './utils.transfer.js';
26
35
  import { isAsyncIterable, settleToolOutput } from './utils.tooloutput.js';
27
36
  import { validateIdentifier } from './utils.validation.js';
28
- import type { IActiveRun, IResultRead, IRunReadCall } from './interfaces.flexharness.js';
37
+ import type { IActiveRun, IResultRead, IRunReadCall, IStoredSessionState } from './interfaces.flexharness.js';
29
38
  import type { FlexHarnessCore } from './classes.flexharness.core.js';
30
39
 
31
40
  const notShared = Symbol('not shared');
@@ -36,6 +45,95 @@ const notShared = Symbol('not shared');
36
45
  export class FlexHarnessToolDispatch<TScope> {
37
46
  constructor(private readonly core: FlexHarnessCore<TScope>) {}
38
47
 
48
+ private async inspectionSession(
49
+ scopeId: string,
50
+ sessionId: string,
51
+ generation: IFlexSessionGeneration,
52
+ signal?: AbortSignal,
53
+ ): Promise<IStoredSessionState> {
54
+ validateIdentifier(generation?.sessionGenerationId, 'sessionGenerationId');
55
+ requireTransferIdentifier(generation.sessionGenerationId, 'sessionGenerationId');
56
+ if (!Number.isSafeInteger(generation.sessionGenerationSequence) || generation.sessionGenerationSequence < 1) {
57
+ throw new FlexHarnessValidationError('sessionGenerationSequence must be a positive safe integer.');
58
+ }
59
+ const throwIfAborted = () => {
60
+ if (signal?.aborted) throw signal.reason ?? new FlexHarnessAbortError('The tool inspection was aborted.');
61
+ };
62
+ throwIfAborted();
63
+ let onAbort: (() => void) | undefined;
64
+ const aborted = signal === undefined ? undefined : new Promise<never>((_resolve, reject) => {
65
+ onAbort = () => reject(signal.reason ?? new FlexHarnessAbortError('The tool inspection was aborted.'));
66
+ signal.addEventListener('abort', onAbort, { once: true });
67
+ if (signal.aborted) onAbort();
68
+ });
69
+ try {
70
+ const stateRead = this.core.resolveState(scopeId, sessionId);
71
+ const { state } = await (aborted ? Promise.race([stateRead, aborted]) : stateRead);
72
+ throwIfAborted();
73
+ const barrier = this.core.sessionReadBarrier(state, sessionId);
74
+ await (aborted ? Promise.race([barrier, aborted]) : barrier);
75
+ throwIfAborted();
76
+ this.core.assertStateAcceptingWork(state);
77
+ const stored = this.core.requireSession(state, sessionId);
78
+ if (stored.session.sessionGenerationId !== generation.sessionGenerationId
79
+ || stored.session.sessionGenerationSequence !== generation.sessionGenerationSequence) {
80
+ throw new FlexHarnessUncertainToolInspectionStaleError(sessionId);
81
+ }
82
+ return stored;
83
+ } finally {
84
+ if (signal && onAbort) signal.removeEventListener('abort', onAbort);
85
+ }
86
+ }
87
+
88
+ private inspectionMetadata(
89
+ intent: plugins.IAgentUncertainToolExecutionMetadata,
90
+ ): TFlexUncertainToolExecutionMetadata {
91
+ return {
92
+ intentId: this.core.boundedIdentifier(intent.intentId, 'intentId'),
93
+ generationId: this.core.boundedIdentifier(intent.generationId, 'generationId'),
94
+ toolCallId: this.core.boundedIdentifier(intent.toolCallId, 'toolCallId'),
95
+ toolName: this.core.boundedIdentifier(intent.toolName, 'toolName'),
96
+ timestamp: new Date(intent.timestamp).toISOString(),
97
+ };
98
+ }
99
+
100
+ public async pageUncertainToolExecutions(
101
+ scopeId: string,
102
+ sessionId: string,
103
+ options: IFlexUncertainToolExecutionPageOptions,
104
+ signal?: AbortSignal,
105
+ ): Promise<IFlexUncertainToolExecutionPage> {
106
+ const limit = options?.limit ?? 128;
107
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > 128) {
108
+ throw new FlexHarnessValidationError('Uncertain tool page limit must be between 1 and 128.');
109
+ }
110
+ if (options?.afterIntentId !== undefined) {
111
+ validateIdentifier(options.afterIntentId, 'afterIntentId');
112
+ requireTransferIdentifier(options.afterIntentId, 'afterIntentId');
113
+ }
114
+ const stored = await this.inspectionSession(scopeId, sessionId, options, signal);
115
+ const page = stored.agentSession.pageUncertainToolExecutions(options.afterIntentId, limit);
116
+ if (!page) throw new FlexHarnessUncertainToolCursorStaleError(options.afterIntentId!);
117
+ return {
118
+ tools: page.tools.map((intent) => this.inspectionMetadata(intent)),
119
+ ...(page.nextAfterIntentId === undefined ? {} : { nextAfterIntentId: page.nextAfterIntentId }),
120
+ };
121
+ }
122
+
123
+ public async getUncertainToolExecution(
124
+ scopeId: string,
125
+ sessionId: string,
126
+ intentId: string,
127
+ generation: IFlexSessionGeneration,
128
+ signal?: AbortSignal,
129
+ ): Promise<TFlexUncertainToolExecutionMetadata | null> {
130
+ validateIdentifier(intentId, 'intentId');
131
+ requireTransferIdentifier(intentId, 'intentId');
132
+ const stored = await this.inspectionSession(scopeId, sessionId, generation, signal);
133
+ const intent = stored.agentSession.getUncertainToolExecution(intentId);
134
+ return intent ? this.inspectionMetadata(intent) : null;
135
+ }
136
+
39
137
  public async listUncertainToolExecutions(
40
138
  scopeId: string,
41
139
  sessionId: string,
@@ -44,6 +44,9 @@ import type {
44
44
  IFlexSlashCommandDescriptor,
45
45
  IFlexSlashCommandExecutionOptions,
46
46
  IFlexUncertainToolExecution,
47
+ IFlexUncertainToolExecutionPage,
48
+ IFlexUncertainToolExecutionPageOptions,
49
+ IFlexSessionGeneration,
47
50
  IFlexUndoSessionResult,
48
51
  IFlexUpdateSessionOptions,
49
52
  IFlexUpdateProjectTaskInput,
@@ -54,6 +57,7 @@ import type {
54
57
  TFlexPrompt,
55
58
  TFlexSlashCommandExecutionResult,
56
59
  TFlexToolExecutionReconciliation,
60
+ TFlexUncertainToolExecutionMetadata,
57
61
  } from './interfaces.js';
58
62
  import { FlexHarnessCore } from './classes.flexharness.core.js';
59
63
 
@@ -504,6 +508,25 @@ export class FlexHarness<TScope = unknown> {
504
508
  return this.core.toolDispatch.listUncertainToolExecutions(scopeId, sessionId);
505
509
  }
506
510
 
511
+ public pageUncertainToolExecutions(
512
+ scopeId: string,
513
+ sessionId: string,
514
+ options: IFlexUncertainToolExecutionPageOptions,
515
+ signal?: AbortSignal,
516
+ ): Promise<IFlexUncertainToolExecutionPage> {
517
+ return this.core.toolDispatch.pageUncertainToolExecutions(scopeId, sessionId, options, signal);
518
+ }
519
+
520
+ public getUncertainToolExecution(
521
+ scopeId: string,
522
+ sessionId: string,
523
+ intentId: string,
524
+ generation: IFlexSessionGeneration,
525
+ signal?: AbortSignal,
526
+ ): Promise<TFlexUncertainToolExecutionMetadata | null> {
527
+ return this.core.toolDispatch.getUncertainToolExecution(scopeId, sessionId, intentId, generation, signal);
528
+ }
529
+
507
530
  public reconcileToolExecution(
508
531
  scopeId: string,
509
532
  sessionId: string,
@@ -6,15 +6,21 @@ import {
6
6
  FlexHarnessValidationError,
7
7
  } from './errors.js';
8
8
  import type {
9
+ IFlexSession,
10
+ IFlexSessionRecoveryCleanState,
11
+ TFlexSessionRecoveryState,
9
12
  IFlexScopeRecoverySnapshot,
10
13
  IFlexScopeRecoveryStore,
14
+ IFlexScopeRecoveryStoreV2,
11
15
  IFlexScopeSnapshot,
12
16
  IFlexScopeStore,
13
17
  IFlexSessionLocalScopeStore,
18
+ TFlexScopeRecoverySnapshot,
14
19
  } from './interfaces.js';
15
20
  import {
16
21
  assertFlexScopeSnapshot,
17
22
  assertJsonSerializable,
23
+ canonicalJson,
18
24
  cloneSerializable,
19
25
  } from './utils.json.js';
20
26
  import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
@@ -34,35 +40,100 @@ function assertRecoverySessionIds(value: unknown): asserts value is string[] {
34
40
  }
35
41
  }
36
42
 
37
- /** Strict sidecar validation shared by recovery-store adapters; scope snapshots stay schema 1. */
38
- export function assertFlexScopeRecoverySnapshot(
43
+ const isDigest = (value: unknown): value is string =>
44
+ typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
45
+
46
+ function assertRecoveryHead(value: unknown, path: string): void {
47
+ assertRecord(value, path);
48
+ assertExactKeys(value, ['incarnationId', 'revision', 'contentRoot'], path);
49
+ if (typeof value.incarnationId !== 'string' || !value.incarnationId.trim()
50
+ || !Number.isSafeInteger(value.revision) || Number(value.revision) < 1
51
+ || !isDigest(value.contentRoot)) {
52
+ throw new FlexHarnessStoreFormatError(`${path} must identify one rooted log incarnation and revision.`);
53
+ }
54
+ }
55
+
56
+ function assertSessionRecoveryState(value: unknown, path: string): asserts value is TFlexSessionRecoveryState {
57
+ assertRecord(value, path);
58
+ if (typeof value.sessionId !== 'string' || !value.sessionId.trim()) {
59
+ throw new FlexHarnessStoreFormatError(`${path}.sessionId must be a non-empty string.`);
60
+ }
61
+ if (value.state === 'dirty') {
62
+ assertExactKeys(value, ['sessionId', 'state'], path);
63
+ return;
64
+ }
65
+ if (value.state !== 'clean') {
66
+ throw new FlexHarnessStoreFormatError(`${path}.state must be dirty or clean.`);
67
+ }
68
+ assertExactKeys(value, [
69
+ 'sessionId', 'state', 'sessionGenerationId', 'sessionGenerationSequence',
70
+ 'sessionDigest', 'projection', 'agentEvents',
71
+ ], path);
72
+ if (typeof value.sessionGenerationId !== 'string' || !value.sessionGenerationId.trim()
73
+ || !Number.isSafeInteger(value.sessionGenerationSequence)
74
+ || Number(value.sessionGenerationSequence) < 1
75
+ || !isDigest(value.sessionDigest)) {
76
+ throw new FlexHarnessStoreFormatError(`${path} must bind an exact session generation and digest.`);
77
+ }
78
+ assertRecoveryHead(value.projection, `${path}.projection`);
79
+ assertRecoveryHead(value.agentEvents, `${path}.agentEvents`);
80
+ }
81
+
82
+ /** Strict validation for the explicit versioned sidecar capability. */
83
+ export function assertFlexScopeRecoverySnapshotVersioned(
39
84
  value: unknown,
40
- ): asserts value is IFlexScopeRecoverySnapshot {
85
+ ): asserts value is TFlexScopeRecoverySnapshot {
41
86
  assertJsonSerializable(value, '$scopeRecovery');
42
87
  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.');
88
+ if (value.schemaVersion === 1) {
89
+ assertExactKeys(value, [
90
+ 'schemaVersion', 'revision', 'catalogueRevision', 'catalogueDigest', 'recoverySessionIds',
91
+ ], '$scopeRecovery');
92
+ assertRecoverySessionIds(value.recoverySessionIds);
93
+ } else if (value.schemaVersion === 2) {
94
+ assertExactKeys(value, [
95
+ 'schemaVersion', 'revision', 'catalogueRevision', 'catalogueDigest', 'sessionStates',
96
+ ], '$scopeRecovery');
97
+ if (!Array.isArray(value.sessionStates)) {
98
+ throw new FlexHarnessStoreFormatError('Scope recovery sessionStates must be an array.');
99
+ }
100
+ let previous = '';
101
+ for (const [index, state] of value.sessionStates.entries()) {
102
+ assertSessionRecoveryState(state, `$scopeRecovery.sessionStates[${index}]`);
103
+ if (state.sessionId <= previous) {
104
+ throw new FlexHarnessStoreFormatError('Scope recovery sessionStates must have unique, sorted session ids.');
105
+ }
106
+ previous = state.sessionId;
107
+ }
108
+ } else {
109
+ throw new FlexHarnessStoreFormatError('Scope recovery schemaVersion must be 1 or 2.');
48
110
  }
49
111
  for (const key of ['revision', 'catalogueRevision'] as const) {
50
112
  if (!Number.isSafeInteger(value[key]) || Number(value[key]) < 0) {
51
113
  throw new FlexHarnessStoreFormatError(`Scope recovery ${key} must be a non-negative safe integer.`);
52
114
  }
53
115
  }
54
- if (typeof value.catalogueDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.catalogueDigest)) {
116
+ if (!isDigest(value.catalogueDigest)) {
55
117
  throw new FlexHarnessStoreFormatError('Scope recovery catalogueDigest must be a lowercase SHA-256 digest.');
56
118
  }
57
- assertRecoverySessionIds(value.recoverySessionIds);
119
+ }
120
+
121
+ /** Strict schema-1 validation for the original recovery-store contract. */
122
+ export function assertFlexScopeRecoverySnapshot(
123
+ value: unknown,
124
+ ): asserts value is IFlexScopeRecoverySnapshot {
125
+ assertFlexScopeRecoverySnapshotVersioned(value);
126
+ if (value.schemaVersion !== 1) {
127
+ throw new FlexHarnessStoreFormatError('Scope recovery schemaVersion must be 1.');
128
+ }
58
129
  }
59
130
 
60
131
  /** Checks the sidecar CAS admission rule and copies the caller-owned value before a backend awaits. */
61
- export function validateFlexScopeRecoverySave(
62
- snapshot: IFlexScopeRecoverySnapshot,
132
+ export function validateFlexScopeRecoverySave<TSnapshot extends TFlexScopeRecoverySnapshot>(
133
+ snapshot: TSnapshot,
63
134
  expectedRevision: number,
64
- ): IFlexScopeRecoverySnapshot {
65
- assertFlexScopeRecoverySnapshot(snapshot);
135
+ ): TSnapshot {
136
+ assertFlexScopeRecoverySnapshotVersioned(snapshot);
66
137
  validateExpectedRevision(expectedRevision);
67
138
  if (snapshot.revision !== expectedRevision + 1) {
68
139
  throw new FlexHarnessStoreFormatError(
@@ -72,6 +143,30 @@ export function validateFlexScopeRecoverySave(
72
143
  return cloneSerializable(snapshot);
73
144
  }
74
145
 
146
+ /** SHA-256 of one canonical IFlexSession, independent of object-key insertion order. */
147
+ export function flexSessionDigest(session: IFlexSession): string {
148
+ const json = canonicalJson(session);
149
+ if (json === undefined) throw new FlexHarnessStoreFormatError('Session metadata is not canonical JSON.');
150
+ return plugins.crypto.createHash('sha256').update(json).digest('hex');
151
+ }
152
+
153
+ function recoveryStates(recovery: TFlexScopeRecoverySnapshot | undefined): TFlexSessionRecoveryState[] {
154
+ return recovery?.schemaVersion === 2
155
+ ? cloneSerializable(recovery.sessionStates)
156
+ : (recovery?.recoverySessionIds ?? []).map((sessionId) => ({ sessionId, state: 'dirty' as const }));
157
+ }
158
+
159
+ function sortedStates(states: TFlexSessionRecoveryState[]): TFlexSessionRecoveryState[] {
160
+ return states.sort((left, right) => left.sessionId < right.sessionId ? -1 : left.sessionId > right.sessionId ? 1 : 0);
161
+ }
162
+
163
+ function cleanMatchesSession(clean: IFlexSessionRecoveryCleanState, session: IFlexSession | undefined): boolean {
164
+ return session !== undefined
165
+ && clean.sessionGenerationId === session.sessionGenerationId
166
+ && clean.sessionGenerationSequence === session.sessionGenerationSequence
167
+ && clean.sessionDigest === flexSessionDigest(session);
168
+ }
169
+
75
170
  function canonicalCatalogueJson(value: unknown): string {
76
171
  if (Array.isArray(value)) return `[${value.map(canonicalCatalogueJson).join(',')}]`;
77
172
  if (value !== null && typeof value === 'object') {
@@ -97,10 +192,16 @@ function catalogueDigest(snapshot: IFlexScopeSnapshot | undefined): string {
97
192
 
98
193
  interface IRecoveryEvidence {
99
194
  snapshot: IFlexScopeSnapshot | undefined;
100
- recovery: IFlexScopeRecoverySnapshot | undefined;
195
+ recovery: TFlexScopeRecoverySnapshot | undefined;
101
196
  qualified: boolean;
102
197
  }
103
198
 
199
+ function isVersionedRecoveryStore(
200
+ store: IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2,
201
+ ): store is IFlexScopeRecoveryStoreV2 {
202
+ return 'recoverySchemaVersion' in store && store.recoverySchemaVersion === 2;
203
+ }
204
+
104
205
  /**
105
206
  * Adds session-local recovery to any durable scope CAS store without changing its snapshots.
106
207
  *
@@ -117,7 +218,7 @@ interface IRecoveryEvidence {
117
218
  * a failure in that gap is CommitUncertain and never implicitly qualifies the resulting catalogue.
118
219
  */
119
220
  export class RecoverableFlexScopeStore implements IFlexScopeStore {
120
- private static readonly lanes = new WeakMap<IFlexScopeRecoveryStore, Map<string, Promise<void>>>();
221
+ private static readonly lanes = new WeakMap<IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2, Map<string, Promise<void>>>();
121
222
 
122
223
  public readonly sessionLocal: IFlexSessionLocalScopeStore = {
123
224
  releaseOwnership: (storageKey) => this.recoveryStore.deactivateWriteProvenance(storageKey),
@@ -132,7 +233,7 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
132
233
 
133
234
  constructor(
134
235
  private readonly scopes: IFlexScopeStore,
135
- private readonly recoveryStore: IFlexScopeRecoveryStore,
236
+ private readonly recoveryStore: IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2,
136
237
  ) {}
137
238
 
138
239
  private inLane<T>(storageKey: string, operation: () => Promise<T>): Promise<T> {
@@ -163,21 +264,42 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
163
264
  }
164
265
 
165
266
  private async readEvidence(storageKey: string): Promise<IRecoveryEvidence> {
166
- const provenance = await this.recoveryStore.loadWriteProvenance(storageKey);
167
- const snapshot = await this.scopes.load(storageKey);
168
- if (snapshot !== undefined) assertFlexScopeSnapshot(snapshot);
169
- const recovery = await this.recoveryStore.load(storageKey);
170
- if (recovery !== undefined) assertFlexScopeRecoverySnapshot(recovery);
171
- const qualified = provenance && (recovery === undefined
172
- ? snapshot === undefined
173
- : recovery.catalogueRevision === (snapshot?.revision ?? 0)
174
- && recovery.catalogueDigest === catalogueDigest(snapshot));
175
- if (!qualified) this.recoveryStore.deactivateWriteProvenance(storageKey);
176
- return {
177
- snapshot: snapshot === undefined ? undefined : cloneSerializable(snapshot),
178
- recovery: recovery === undefined ? undefined : cloneSerializable(recovery),
179
- qualified,
180
- };
267
+ try {
268
+ const provenance = await this.recoveryStore.loadWriteProvenance(storageKey);
269
+ const snapshot = await this.scopes.load(storageKey);
270
+ if (snapshot !== undefined) assertFlexScopeSnapshot(snapshot);
271
+ let recovery = await this.recoveryStore.load(storageKey);
272
+ if (recovery !== undefined) {
273
+ assertFlexScopeRecoverySnapshotVersioned(recovery);
274
+ if (recovery.schemaVersion === 2 && !isVersionedRecoveryStore(this.recoveryStore)) {
275
+ throw new FlexHarnessStoreFormatError('A schema-2 sidecar requires a versioned recovery store.');
276
+ }
277
+ if (recovery.schemaVersion === 2 && recovery.sessionStates.some((entry) => entry.state === 'clean')) {
278
+ // This compatibility writer cannot mark every producer before its effect. Retire every
279
+ // inherited clean claim before a session-local scope can admit work after a rollback.
280
+ const demoted: TFlexScopeRecoverySnapshot = {
281
+ ...recovery,
282
+ revision: recovery.revision + 1,
283
+ sessionStates: recovery.sessionStates.map((entry) => ({ sessionId: entry.sessionId, state: 'dirty' })),
284
+ };
285
+ await this.saveRecovery(storageKey, demoted, recovery.revision);
286
+ recovery = demoted;
287
+ }
288
+ }
289
+ const qualified = provenance && (recovery === undefined
290
+ ? snapshot === undefined
291
+ : recovery.catalogueRevision === (snapshot?.revision ?? 0)
292
+ && recovery.catalogueDigest === catalogueDigest(snapshot));
293
+ if (!qualified) this.recoveryStore.deactivateWriteProvenance(storageKey);
294
+ return {
295
+ snapshot: snapshot === undefined ? undefined : cloneSerializable(snapshot),
296
+ recovery: recovery === undefined ? undefined : cloneSerializable(recovery),
297
+ qualified,
298
+ };
299
+ } catch (error) {
300
+ this.recoveryStore.deactivateWriteProvenance(storageKey);
301
+ throw error;
302
+ }
181
303
  }
182
304
 
183
305
  private loadCatalogue(storageKey: string): ReturnType<IFlexSessionLocalScopeStore['loadCatalogue']> {
@@ -186,7 +308,15 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
186
308
  return {
187
309
  snapshot: evidence.snapshot,
188
310
  qualified: evidence.qualified,
189
- recoverySessionIds: evidence.recovery?.recoverySessionIds ?? [],
311
+ // readEvidence has retired schema-2 clean claims. Until the complete producer gate is
312
+ // activated, every session in that sidecar takes normal recovery.
313
+ recoverySessionIds: evidence.recovery?.schemaVersion === 2
314
+ ? [...new Set([
315
+ ...(evidence.snapshot?.sessions.map((session) => session.sessionId) ?? []),
316
+ ...(evidence.snapshot?.tombstones.map((tombstone) => tombstone.sessionId) ?? []),
317
+ ...evidence.recovery.sessionStates.map((entry) => entry.sessionId),
318
+ ])].sort()
319
+ : evidence.recovery?.recoverySessionIds ?? [],
190
320
  };
191
321
  });
192
322
  }
@@ -199,20 +329,37 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
199
329
  }
200
330
  }
201
331
 
332
+ private saveRecovery(
333
+ storageKey: string,
334
+ snapshot: TFlexScopeRecoverySnapshot,
335
+ expectedRevision: number,
336
+ ): Promise<void> {
337
+ if (isVersionedRecoveryStore(this.recoveryStore)) {
338
+ return this.recoveryStore.save(storageKey, snapshot, expectedRevision);
339
+ }
340
+ if (snapshot.schemaVersion !== 1) {
341
+ throw new FlexHarnessStoreFormatError('A schema-2 sidecar requires a versioned recovery store.');
342
+ }
343
+ return this.recoveryStore.save(storageKey, snapshot, expectedRevision);
344
+ }
345
+
202
346
  private saveProof(
203
347
  storageKey: string,
204
348
  snapshot: IFlexScopeSnapshot | undefined,
205
- recovery: IFlexScopeRecoverySnapshot | undefined,
206
- recoverySessionIds: string[],
349
+ recovery: TFlexScopeRecoverySnapshot | undefined,
350
+ states: TFlexSessionRecoveryState[],
207
351
  ): Promise<void> {
208
352
  const expectedRevision = recovery?.revision ?? 0;
209
- return this.recoveryStore.save(storageKey, {
210
- schemaVersion: 1,
353
+ const common = {
211
354
  revision: expectedRevision + 1,
212
355
  catalogueRevision: snapshot?.revision ?? 0,
213
356
  catalogueDigest: catalogueDigest(snapshot),
214
- recoverySessionIds,
215
- }, expectedRevision);
357
+ };
358
+ return this.saveRecovery(storageKey, recovery?.schemaVersion === 2
359
+ ? { schemaVersion: 2, ...common, sessionStates: sortedStates(states) }
360
+ : { schemaVersion: 1, ...common,
361
+ recoverySessionIds: sortedStates(states).filter((entry) => entry.state === 'dirty')
362
+ .map((entry) => entry.sessionId) }, expectedRevision);
216
363
  }
217
364
 
218
365
  private async saveCatalogue(
@@ -226,8 +373,13 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
226
373
  this.assertQualified(storageKey, evidence);
227
374
  await this.scopes.save(storageKey, validated, expectedRevision);
228
375
  try {
376
+ const sessions = new Map(validated.sessions.map((session) => [session.sessionId, session]));
377
+ const states = recoveryStates(evidence.recovery).map((entry): TFlexSessionRecoveryState =>
378
+ entry.state === 'clean' && !cleanMatchesSession(entry, sessions.get(entry.sessionId))
379
+ ? { sessionId: entry.sessionId, state: 'dirty' }
380
+ : entry);
229
381
  await this.saveProof(
230
- storageKey, validated, evidence.recovery, evidence.recovery?.recoverySessionIds ?? [],
382
+ storageKey, validated, evidence.recovery, states,
231
383
  );
232
384
  } catch (cause) {
233
385
  throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
@@ -243,22 +395,32 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
243
395
  return this.inLane(storageKey, async () => {
244
396
  const evidence = await this.readEvidence(storageKey);
245
397
  if (!required) this.assertQualified(storageKey, evidence);
246
- const ids = evidence.recovery?.recoverySessionIds ?? [];
247
- if (ids.includes(sessionId) === required) return;
248
- const recoverySessionIds = required ? [...ids, sessionId] : ids.filter((id) => id !== sessionId);
398
+ if (!required && evidence.recovery?.schemaVersion === 2
399
+ && evidence.snapshot?.sessions.some((session) => session.sessionId === sessionId)) {
400
+ throw new FlexHarnessValidationError('A live schema-2 session requires an exact clean publication.');
401
+ }
402
+ const states = recoveryStates(evidence.recovery);
403
+ const current = states.find((entry) => entry.sessionId === sessionId);
404
+ if (required && current?.state === 'dirty') return;
405
+ if (!required && current === undefined) return;
406
+ const next = states.filter((entry) => entry.sessionId !== sessionId);
407
+ if (required) next.push({ sessionId, state: 'dirty' });
249
408
  if (evidence.qualified) {
250
- await this.saveProof(storageKey, evidence.snapshot, evidence.recovery, recoverySessionIds);
409
+ await this.saveProof(storageKey, evidence.snapshot, evidence.recovery, next);
251
410
  } else {
252
411
  // Adding an obligation is safe without qualification, but it must not create a proof of
253
412
  // the unqualified snapshot. An absent proof remains the proof of an absent catalogue.
254
413
  const expectedRevision = evidence.recovery?.revision ?? 0;
255
- await this.recoveryStore.save(storageKey, {
256
- schemaVersion: 1,
414
+ const common = {
257
415
  revision: expectedRevision + 1,
258
416
  catalogueRevision: evidence.recovery?.catalogueRevision ?? 0,
259
417
  catalogueDigest: evidence.recovery?.catalogueDigest ?? catalogueDigest(undefined),
260
- recoverySessionIds,
261
- }, expectedRevision);
418
+ };
419
+ await this.saveRecovery(storageKey, evidence.recovery?.schemaVersion === 2
420
+ ? { schemaVersion: 2, ...common, sessionStates: sortedStates(next) }
421
+ : { schemaVersion: 1, ...common,
422
+ recoverySessionIds: sortedStates(next).filter((entry) => entry.state === 'dirty')
423
+ .map((entry) => entry.sessionId) }, expectedRevision);
262
424
  }
263
425
  });
264
426
  }
@@ -281,7 +443,16 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
281
443
  // Publish the proof inactive: a crash/failure before witness qualification cannot bless it.
282
444
  this.recoveryStore.deactivateWriteProvenance(storageKey);
283
445
  try {
284
- await this.saveProof(storageKey, validated, evidence.recovery, ids);
446
+ const previous = recoveryStates(evidence.recovery);
447
+ const sessions = new Map(validated.sessions.map((session) => [session.sessionId, session]));
448
+ const states: TFlexSessionRecoveryState[] = ids.map((sessionId) => ({ sessionId, state: 'dirty' }));
449
+ if (evidence.recovery?.schemaVersion === 2) {
450
+ for (const entry of previous) {
451
+ if (entry.state === 'clean' && !ids.includes(entry.sessionId)
452
+ && cleanMatchesSession(entry, sessions.get(entry.sessionId))) states.push(entry);
453
+ }
454
+ }
455
+ await this.saveProof(storageKey, validated, evidence.recovery, states);
285
456
  await this.recoveryStore.qualifyWriteProvenance(storageKey);
286
457
  } catch (cause) {
287
458
  throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
package/ts/errors.ts CHANGED
@@ -58,6 +58,22 @@ export class FlexHarnessUnresolvedToolExecutionsError extends FlexHarnessError {
58
58
  }
59
59
  }
60
60
 
61
+ /** The inspected session was replaced after the caller observed its generation. */
62
+ export class FlexHarnessUncertainToolInspectionStaleError extends FlexHarnessError {
63
+ constructor(sessionId: string) {
64
+ super('FLEX_UNCERTAIN_TOOL_INSPECTION_STALE', `Session "${sessionId}" changed generation during tool inspection.`);
65
+ this.name = 'FlexHarnessUncertainToolInspectionStaleError';
66
+ }
67
+ }
68
+
69
+ /** The cursor intent was resolved or removed; inspection must restart at the first page. */
70
+ export class FlexHarnessUncertainToolCursorStaleError extends FlexHarnessError {
71
+ constructor(intentId: string) {
72
+ super('FLEX_UNCERTAIN_TOOL_CURSOR_STALE', `Uncertain tool cursor "${intentId}" is stale.`);
73
+ this.name = 'FlexHarnessUncertainToolCursorStaleError';
74
+ }
75
+ }
76
+
61
77
  export type TFlexSteerRejection = 'not-running' | 'duplicate';
62
78
 
63
79
  /**
@@ -139,7 +139,7 @@ export interface IStoredSessionState {
139
139
  permissionRevision: number;
140
140
  permissionQueue: Promise<void>;
141
141
  eventStore: plugins.IAgentEventStore;
142
- agentSession: plugins.IAgentContinuationSession;
142
+ agentSession: plugins.IAgentContinuationSession & plugins.IAgentUncertainToolInspectionSession;
143
143
  agentSessionAbortCompleted: boolean;
144
144
  agentSessionCloseCompleted: boolean;
145
145
  agentEventStoreReleased: boolean;