@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.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/classes.flexharness.core.js +1 -1
- package/dist_ts/classes.flexharness.d.ts +3 -1
- package/dist_ts/classes.flexharness.js +7 -1
- package/dist_ts/classes.flexharness.tooldispatch.d.ts +5 -1
- package/dist_ts/classes.flexharness.tooldispatch.js +74 -2
- package/dist_ts/classes.scoperecovery.d.ts +9 -4
- package/dist_ts/classes.scoperecovery.js +196 -45
- package/dist_ts/errors.d.ts +8 -0
- package/dist_ts/errors.js +15 -1
- package/dist_ts/interfaces.d.ts +50 -0
- package/dist_ts/interfaces.flexharness.d.ts +1 -1
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/plugins.d.ts +1 -1
- package/dist_ts/plugins.js +1 -1
- package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +4 -3
- package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +1 -0
- package/dist_ts_stores_nosqldb/classes.recordstore.js +6 -2
- package/package.json +3 -3
- package/readme.md +10 -1
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +2 -2
- package/ts/classes.flexharness.tooldispatch.ts +100 -2
- package/ts/classes.flexharness.ts +23 -0
- package/ts/classes.scoperecovery.ts +220 -49
- package/ts/errors.ts +16 -0
- package/ts/interfaces.flexharness.ts +1 -1
- package/ts/interfaces.ts +62 -0
- package/ts/plugins.ts +2 -0
- package/ts/readme.md +10 -1
- package/ts_stores_nosqldb/classes.nosqldbstores.ts +8 -7
- package/ts_stores_nosqldb/classes.recordstore.ts +6 -1
- package/ts_stores_nosqldb/readme.md +3 -1
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
import * as plugins from './plugins.js';
|
|
2
|
-
import {
|
|
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
|
-
|
|
38
|
-
|
|
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
|
|
85
|
+
): asserts value is TFlexScopeRecoverySnapshot {
|
|
41
86
|
assertJsonSerializable(value, '$scopeRecovery');
|
|
42
87
|
assertRecord(value, '$scopeRecovery');
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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 (
|
|
116
|
+
if (!isDigest(value.catalogueDigest)) {
|
|
55
117
|
throw new FlexHarnessStoreFormatError('Scope recovery catalogueDigest must be a lowercase SHA-256 digest.');
|
|
56
118
|
}
|
|
57
|
-
|
|
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:
|
|
132
|
+
export function validateFlexScopeRecoverySave<TSnapshot extends TFlexScopeRecoverySnapshot>(
|
|
133
|
+
snapshot: TSnapshot,
|
|
63
134
|
expectedRevision: number,
|
|
64
|
-
):
|
|
65
|
-
|
|
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:
|
|
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
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
|
|
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:
|
|
206
|
-
|
|
349
|
+
recovery: TFlexScopeRecoverySnapshot | undefined,
|
|
350
|
+
states: TFlexSessionRecoveryState[],
|
|
207
351
|
): Promise<void> {
|
|
208
352
|
const expectedRevision = recovery?.revision ?? 0;
|
|
209
|
-
|
|
210
|
-
schemaVersion: 1,
|
|
353
|
+
const common = {
|
|
211
354
|
revision: expectedRevision + 1,
|
|
212
355
|
catalogueRevision: snapshot?.revision ?? 0,
|
|
213
356
|
catalogueDigest: catalogueDigest(snapshot),
|
|
214
|
-
|
|
215
|
-
|
|
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,
|
|
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
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
261
|
-
|
|
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
|
-
|
|
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;
|