@modelprofile.com/flexharness 18.5.0 → 18.7.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 +5 -2
- package/dist_ts/classes.flexharness.d.ts +3 -1
- package/dist_ts/classes.flexharness.js +7 -1
- package/dist_ts/classes.flexharness.prompts.d.ts +2 -0
- package/dist_ts/classes.flexharness.prompts.js +11 -2
- package/dist_ts/classes.flexharness.tooldispatch.d.ts +5 -1
- package/dist_ts/classes.flexharness.tooldispatch.js +74 -2
- package/dist_ts/errors.d.ts +13 -0
- package/dist_ts/errors.js +24 -1
- package/dist_ts/interfaces.d.ts +17 -0
- package/dist_ts/interfaces.flexharness.d.ts +1 -1
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/plugins.d.ts +3 -3
- package/dist_ts/plugins.js +3 -3
- package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +11 -1
- package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +12 -0
- package/dist_ts_stores_nosqldb/classes.recordstore.js +93 -9
- package/package.json +3 -3
- package/readme.md +10 -1
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +6 -2
- package/ts/classes.flexharness.prompts.ts +17 -0
- package/ts/classes.flexharness.tooldispatch.ts +100 -2
- package/ts/classes.flexharness.ts +23 -0
- package/ts/errors.ts +30 -0
- package/ts/interfaces.flexharness.ts +1 -1
- package/ts/interfaces.ts +21 -0
- package/ts/plugins.ts +4 -0
- package/ts/readme.md +10 -1
- package/ts_stores_nosqldb/classes.nosqldbstores.ts +12 -0
- package/ts_stores_nosqldb/classes.recordstore.ts +100 -7
- package/ts_stores_nosqldb/readme.md +2 -0
|
@@ -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,
|
package/ts/errors.ts
CHANGED
|
@@ -44,6 +44,36 @@ export class FlexHarnessSessionBusyError extends FlexHarnessError {
|
|
|
44
44
|
}
|
|
45
45
|
}
|
|
46
46
|
|
|
47
|
+
/** New input is refused until the controller explicitly reconciles uncertain tool effects. */
|
|
48
|
+
export class FlexHarnessUnresolvedToolExecutionsError extends FlexHarnessError {
|
|
49
|
+
public readonly sessionId: string;
|
|
50
|
+
|
|
51
|
+
constructor(sessionId: string) {
|
|
52
|
+
super(
|
|
53
|
+
'FLEX_UNRESOLVED_TOOL_EXECUTIONS',
|
|
54
|
+
`Session "${sessionId}" has unresolved tool execution intents. Inspect and reconcile them before sending more input.`,
|
|
55
|
+
);
|
|
56
|
+
this.name = 'FlexHarnessUnresolvedToolExecutionsError';
|
|
57
|
+
this.sessionId = sessionId;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
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
|
+
|
|
47
77
|
export type TFlexSteerRejection = 'not-running' | 'duplicate';
|
|
48
78
|
|
|
49
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;
|
package/ts/interfaces.ts
CHANGED
|
@@ -1813,6 +1813,8 @@ export interface IFlexScopeStore {
|
|
|
1813
1813
|
|
|
1814
1814
|
export interface IFlexProjectionStore {
|
|
1815
1815
|
load(storageKey: string, sessionId: string): Promise<TFlexProjectionSnapshot | undefined>;
|
|
1816
|
+
/** Optional bounded content commitment; undefined requires a full load. */
|
|
1817
|
+
loadHead?(storageKey: string, sessionId: string): Promise<IFlexProjectionHead | undefined>;
|
|
1816
1818
|
/**
|
|
1817
1819
|
* Applies `change` to the stored projection while its revision is `expectedRevision`; the
|
|
1818
1820
|
* change's revision is the next one.
|
|
@@ -1826,6 +1828,11 @@ export interface IFlexProjectionStore {
|
|
|
1826
1828
|
deleteSession(storageKey: string, sessionId: string): Promise<void>;
|
|
1827
1829
|
}
|
|
1828
1830
|
|
|
1831
|
+
export interface IFlexProjectionHead {
|
|
1832
|
+
revision: number;
|
|
1833
|
+
contentRoot: string;
|
|
1834
|
+
}
|
|
1835
|
+
|
|
1829
1836
|
export interface IFlexPermissionStore {
|
|
1830
1837
|
load(storageKey: string, sessionId: string): Promise<IFlexPermissionSnapshot | undefined>;
|
|
1831
1838
|
save(
|
|
@@ -2389,6 +2396,20 @@ export interface IFlexUncertainToolExecution {
|
|
|
2389
2396
|
timestamp: string;
|
|
2390
2397
|
}
|
|
2391
2398
|
|
|
2399
|
+
/** Bounded inspection metadata; the tool input never crosses this API. */
|
|
2400
|
+
export type TFlexUncertainToolExecutionMetadata = Omit<IFlexUncertainToolExecution, 'input'>;
|
|
2401
|
+
|
|
2402
|
+
export interface IFlexUncertainToolExecutionPageOptions extends IFlexSessionGeneration {
|
|
2403
|
+
afterIntentId?: string;
|
|
2404
|
+
/** Defaults to 128 and may not exceed 128. */
|
|
2405
|
+
limit?: number;
|
|
2406
|
+
}
|
|
2407
|
+
|
|
2408
|
+
export interface IFlexUncertainToolExecutionPage {
|
|
2409
|
+
tools: TFlexUncertainToolExecutionMetadata[];
|
|
2410
|
+
nextAfterIntentId?: string;
|
|
2411
|
+
}
|
|
2412
|
+
|
|
2392
2413
|
export type TFlexToolExecutionReconciliation =
|
|
2393
2414
|
| {
|
|
2394
2415
|
resolution: 'executed';
|
package/ts/plugins.ts
CHANGED
|
@@ -100,6 +100,7 @@ import {
|
|
|
100
100
|
assertAttachmentResolver,
|
|
101
101
|
AgentPendingInputRejectedError,
|
|
102
102
|
AgentSession,
|
|
103
|
+
AgentUnresolvedToolExecutionsError,
|
|
103
104
|
AgentToolCallScheduler,
|
|
104
105
|
assertAgentContextCompactionSetting,
|
|
105
106
|
buildModelMessages,
|
|
@@ -127,6 +128,7 @@ export {
|
|
|
127
128
|
assertAttachmentResolver,
|
|
128
129
|
AgentPendingInputRejectedError,
|
|
129
130
|
AgentSession,
|
|
131
|
+
AgentUnresolvedToolExecutionsError,
|
|
130
132
|
AgentToolCallScheduler,
|
|
131
133
|
assertAgentContextCompactionSetting,
|
|
132
134
|
buildModelMessages,
|
|
@@ -161,6 +163,8 @@ export type {
|
|
|
161
163
|
IAgentRetryEvent,
|
|
162
164
|
IAgentRunResult,
|
|
163
165
|
IAgentSession,
|
|
166
|
+
IAgentUncertainToolExecutionMetadata,
|
|
167
|
+
IAgentUncertainToolInspectionSession,
|
|
164
168
|
IAgentContinuationSession,
|
|
165
169
|
IAgentSessionOptions,
|
|
166
170
|
IAgentToolCallUpdateEvent,
|
package/ts/readme.md
CHANGED
|
@@ -688,6 +688,11 @@ await harness.listPendingPermissions(scopeId, sessionId);
|
|
|
688
688
|
await harness.respondToPermission(scopeId, sessionId, permissionId, 'once');
|
|
689
689
|
await harness.pushRuntimeEvent(scopeId, sessionId, { type: 'workspace.changed', path: 'src/' });
|
|
690
690
|
await harness.listUncertainToolExecutions(scopeId, sessionId);
|
|
691
|
+
const { sessionGenerationId, sessionGenerationSequence } = await harness.getSession(scopeId, sessionId);
|
|
692
|
+
if (!sessionGenerationId || !sessionGenerationSequence) throw new Error('Session generation is unavailable.');
|
|
693
|
+
const inspection = { sessionGenerationId, sessionGenerationSequence };
|
|
694
|
+
const firstUncertainPage = await harness.pageUncertainToolExecutions(scopeId, sessionId, inspection);
|
|
695
|
+
await harness.getUncertainToolExecution(scopeId, sessionId, intentId, inspection);
|
|
691
696
|
await harness.reconcileToolExecution(scopeId, sessionId, intentId, {
|
|
692
697
|
resolution: 'executed',
|
|
693
698
|
output: { committed: true },
|
|
@@ -773,6 +778,8 @@ When the older releases of a host change no such witness, the host cannot detect
|
|
|
773
778
|
|
|
774
779
|
In-memory and NoSQL stores implement the additive capability. Existing custom stores and `JsonFileFlexHarnessStores` keep their eager behavior; the JSON store creates no new recovery files and cannot opt into session-local loading without a separate capable backend.
|
|
775
780
|
|
|
781
|
+
The NoSQL projection store's optional `loadHead(storageKey, sessionId)` and Agent event store's optional `loadHead(sessionId)` return `{ revision, contentRoot }` from the record head without reading the base, change pages or event bodies. The SHA-256 root commits to the serialized log base and each ordered change; its stored revision and write-token binding advance in the same compare-and-swap as the head. A missing record, legacy unrooted log or head whose revision or write token an older writer advanced without renewing the root returns `undefined`; its next save validates and rewrites the complete log before it can supply a root. Malformed commitment fields fail closed. A full load verifies a current root against the stored base and changes. These heads are content commitments for a future recovery frontier; by themselves they do not make a catalogue session safe for a cold `getSession()` read. Other stores do not advertise bounded heads.
|
|
782
|
+
|
|
776
783
|
### Continuing Without New Input
|
|
777
784
|
|
|
778
785
|
Use `continuePrompt()` after a failed or stopped run whose input remains in context
|
|
@@ -1213,7 +1220,9 @@ Model resolver, tool provider, delegated run admission provider, AgentSession, t
|
|
|
1213
1220
|
|
|
1214
1221
|
`pushRuntimeEvent()` appends a validated JSON event through the canonical AgentSession event store. It is intended for controller-owned context such as workspace changes or external notifications; invalid or non-JSON values fail before persistence.
|
|
1215
1222
|
|
|
1216
|
-
Transactional tool calls persist an execution intent before the tool side effect starts. After an interrupted process, `listUncertainToolExecutions()` exposes intents whose outcome cannot be proven. A controller must inspect the external system and call `reconcileToolExecution()` with `executed`, `not-executed`, or `abandoned-unknown` before allowing dependent work to continue. Reconciliation output is normalized using the same tool-output limits.
|
|
1223
|
+
Transactional tool calls persist an execution intent before the tool side effect starts. After an interrupted process, `listUncertainToolExecutions()` exposes intents whose outcome cannot be proven. While any such intent remains, new prompts, continuations, scheduled and cache-warm turns, and delegated child turns are refused with `FlexHarnessUnresolvedToolExecutionsError` (`FLEX_UNRESOLVED_TOOL_EXECUTIONS`). A prompt queued while the current run's tool was still executing receives one failed queue outcome if that effect remains unresolved at promotion; the caller must explicitly resend it after reconciliation. A steer may join its own running generation while that generation's tool executes, but cannot enter a run with unresolved effects from another generation. A controller must inspect the external system and call `reconcileToolExecution()` with `executed`, `not-executed`, or `abandoned-unknown` before allowing dependent work to continue. Reconciliation output is normalized using the same tool-output limits. After reconciliation, the model sees its authoritative result once, even if an earlier unknown-effect result closed the call in the failed run; both events remain in the audit log. Neither reconciliation nor reopening admission retries a tool or resends input automatically.
|
|
1224
|
+
|
|
1225
|
+
For a bounded inspection view, call `pageUncertainToolExecutions(scopeId, sessionId, { sessionGenerationId, sessionGenerationSequence, afterIntentId?, limit? }, signal?)` or `getUncertainToolExecution(scopeId, sessionId, intentId, { sessionGenerationId, sessionGenerationSequence }, signal?)`. Take the session generation from `getSession()` and keep it fixed across pages. Pages contain only `intentId`, `generationId`, `toolCallId`, `toolName`, and ISO `timestamp`; no tool input or output is read or returned. The default and maximum page size is 128, and `nextAfterIntentId` is present only when another page exists. A changed session generation throws `FlexHarnessUncertainToolInspectionStaleError` (`FLEX_UNCERTAIN_TOOL_INSPECTION_STALE`); an `afterIntentId` that was resolved or removed throws `FlexHarnessUncertainToolCursorStaleError` (`FLEX_UNCERTAIN_TOOL_CURSOR_STALE`), so start again from the first page. Exact lookup returns `null` for an absent or resolved intent. An optional abort signal cancels only that caller's wait. The existing `listUncertainToolExecutions()` still includes tool inputs for controllers that need them.
|
|
1217
1226
|
|
|
1218
1227
|
`agentSessionPolicy` forwards bounded AgentSession session controls for context building, compaction, event retention, change-listener pressure, lease cleanup, archived transaction tombstones, and context-overflow retries. A configured `contextCompactor` receives the projected model messages, only the filtered model-visible covered events, AgentSession's existing `reason` and `abortSignal`, and the exact resolved `scopeId`, `scope`, `storageKey`, and `sessionId` for the invocation causing compaction. The invocation context remains isolated when aliases share one storage key, so integrations can resolve the correct model without global mutable state. If no events are eligible for compaction, `compactSession()` returns without calling the compactor or writing a compaction event; otherwise it writes the canonical event. `archiveSessionEvents()` moves events covered by that compaction into the configured Agent event archive store and returns public archive metadata.
|
|
1219
1228
|
|
|
@@ -193,6 +193,11 @@ class NoSqlProjectionStore implements IFlexProjectionStore {
|
|
|
193
193
|
return this.records.readLog({ domain: 'projection', storageKey, sessionId }, this.log(sessionId));
|
|
194
194
|
}
|
|
195
195
|
|
|
196
|
+
public loadHead(storageKey: string, sessionId: string) {
|
|
197
|
+
providerKey(storageKey, sessionId);
|
|
198
|
+
return this.records.readLogHead({ domain: 'projection', storageKey, sessionId });
|
|
199
|
+
}
|
|
200
|
+
|
|
196
201
|
public async save(
|
|
197
202
|
storageKey: string,
|
|
198
203
|
sessionId: string,
|
|
@@ -344,6 +349,13 @@ class NoSqlAgentEventStore implements plugins.IAgentEventStore {
|
|
|
344
349
|
);
|
|
345
350
|
}
|
|
346
351
|
|
|
352
|
+
public loadHead(sessionId: string) {
|
|
353
|
+
this.assertSession(sessionId);
|
|
354
|
+
return this.records.readLogHead({
|
|
355
|
+
domain: 'agentEvents', storageKey: this.storageKey, sessionId,
|
|
356
|
+
});
|
|
357
|
+
}
|
|
358
|
+
|
|
347
359
|
public async save(
|
|
348
360
|
sessionId: string,
|
|
349
361
|
change: plugins.IAgentEventChange,
|
|
@@ -128,6 +128,11 @@ export class FlexRecordDocument extends plugins.SmartDataDbDoc<FlexRecordDocumen
|
|
|
128
128
|
public blobId!: string | null;
|
|
129
129
|
public chunkCount!: number;
|
|
130
130
|
public payloadSha256!: string | null;
|
|
131
|
+
/** Hash of the log base and every committed change, updated with the head CAS. */
|
|
132
|
+
public contentRoot?: string | null;
|
|
133
|
+
/** The exact head revision and token whose content the root commits. */
|
|
134
|
+
public contentRootRevision?: number;
|
|
135
|
+
public contentRootWriteToken?: string;
|
|
131
136
|
/** Set before the first chunk of this record is written; the record's writes then sweep. */
|
|
132
137
|
public chunked!: boolean;
|
|
133
138
|
public sweepCount!: number;
|
|
@@ -222,6 +227,9 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
|
|
|
222
227
|
'blobId',
|
|
223
228
|
'chunkCount',
|
|
224
229
|
'payloadSha256',
|
|
230
|
+
'contentRoot',
|
|
231
|
+
'contentRootRevision',
|
|
232
|
+
'contentRootWriteToken',
|
|
225
233
|
'chunked',
|
|
226
234
|
'sweepCount',
|
|
227
235
|
'logId',
|
|
@@ -232,7 +240,7 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
|
|
|
232
240
|
'baseLength',
|
|
233
241
|
'retiredLogId',
|
|
234
242
|
],
|
|
235
|
-
numericFields: ['revision', 'chunkCount', 'sweepCount', 'changeCount', 'changeLength', 'baseLength'],
|
|
243
|
+
numericFields: ['revision', 'contentRootRevision', 'chunkCount', 'sweepCount', 'changeCount', 'changeLength', 'baseLength'],
|
|
236
244
|
identityFields: ['recordId'],
|
|
237
245
|
indexes: [
|
|
238
246
|
{ name: 'flexharness_record_id', key: { recordId: 1 }, options: { unique: true } },
|
|
@@ -314,6 +322,12 @@ interface IStoredLog<TSnapshot> {
|
|
|
314
322
|
value?: TSnapshot;
|
|
315
323
|
}
|
|
316
324
|
|
|
325
|
+
/** A content commitment read from one bounded log head, without its base or change pages. */
|
|
326
|
+
export interface IFlexRecordLogHead {
|
|
327
|
+
revision: number;
|
|
328
|
+
contentRoot: string;
|
|
329
|
+
}
|
|
330
|
+
|
|
317
331
|
type TDeletionSelector =
|
|
318
332
|
| { recordId: string; domain: TFlexRecordDomain }
|
|
319
333
|
| { ownerKey: string; domain: TFlexRecordDomain }
|
|
@@ -326,6 +340,31 @@ const deletionBatchSize = 4;
|
|
|
326
340
|
const digest = (value: string): string =>
|
|
327
341
|
plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
|
|
328
342
|
|
|
343
|
+
const logBaseRoot = (text: string): string => digest(JSON.stringify(['flex-record-log-v1', 'base', digest(text)]));
|
|
344
|
+
const logChangeRoot = (root: string, text: string): string =>
|
|
345
|
+
digest(JSON.stringify(['flex-record-log-v1', 'change', root, digest(text)]));
|
|
346
|
+
|
|
347
|
+
/** An older writer may advance a head without knowing these fields; then the root is unqualified. */
|
|
348
|
+
function committedLogRoot(head: FlexRecordDocument, resolved: IResolvedAddress): string | undefined {
|
|
349
|
+
const root = head.contentRoot;
|
|
350
|
+
const revision = head.contentRootRevision;
|
|
351
|
+
const token = head.contentRootWriteToken;
|
|
352
|
+
if (root === undefined || root === null) {
|
|
353
|
+
if (revision !== undefined || token !== undefined) {
|
|
354
|
+
throw new FlexHarnessStoreFormatError(`Incomplete log content commitment at ${resolved.path}.`);
|
|
355
|
+
}
|
|
356
|
+
return undefined;
|
|
357
|
+
}
|
|
358
|
+
if (typeof root !== 'string' || !/^[a-f0-9]{64}$/.test(root)
|
|
359
|
+
|| !Number.isSafeInteger(revision) || Number(revision) < 1
|
|
360
|
+
|| typeof token !== 'string' || token.length === 0
|
|
361
|
+
|| !Number.isSafeInteger(head.revision) || head.revision < 1
|
|
362
|
+
|| typeof head.writeToken !== 'string' || head.writeToken.length === 0) {
|
|
363
|
+
throw new FlexHarnessStoreFormatError(`Invalid log content commitment at ${resolved.path}.`);
|
|
364
|
+
}
|
|
365
|
+
return revision === head.revision && token === head.writeToken ? root : undefined;
|
|
366
|
+
}
|
|
367
|
+
|
|
329
368
|
function splitPayload(text: string): string[] {
|
|
330
369
|
const chunks: string[] = [];
|
|
331
370
|
let start = 0;
|
|
@@ -511,6 +550,33 @@ export class FlexRecordStore {
|
|
|
511
550
|
return this.readVisible(resolved, async () => (await this.loadLog(resolved, log)).value);
|
|
512
551
|
}
|
|
513
552
|
|
|
553
|
+
/** A missing or legacy commitment requires the caller to take the complete log path. */
|
|
554
|
+
public async readLogHead(address: IFlexRecordAddress): Promise<IFlexRecordLogHead | undefined> {
|
|
555
|
+
await this.prepare();
|
|
556
|
+
const resolved = this.resolve(address);
|
|
557
|
+
return this.readVisible(resolved, async () => {
|
|
558
|
+
const head = await this.findHead(resolved);
|
|
559
|
+
if (!head) return undefined;
|
|
560
|
+
const root = committedLogRoot(head, resolved);
|
|
561
|
+
if (head.contentRoot === undefined || head.contentRoot === null) return undefined;
|
|
562
|
+
if (!Number.isSafeInteger(head.revision) || head.revision < 1
|
|
563
|
+
|| typeof head.logId !== 'string' || !head.logId
|
|
564
|
+
|| typeof head.payloadSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(head.payloadSha256)
|
|
565
|
+
|| typeof head.blobId !== 'string' || !head.blobId
|
|
566
|
+
|| head.payload !== null || head.chunked !== true
|
|
567
|
+
|| !Number.isSafeInteger(head.chunkCount) || head.chunkCount < 1
|
|
568
|
+
|| !Number.isSafeInteger(head.changeCount) || head.changeCount < 0
|
|
569
|
+
|| !Array.isArray(head.recentChanges)
|
|
570
|
+
|| head.recentChanges.some((change) => typeof change !== 'string')
|
|
571
|
+
|| head.changeCount < head.recentChanges.length
|
|
572
|
+
|| head.recentChanges.reduce((length, change) => length + change.length, 0)
|
|
573
|
+
> FLEX_RECORD_INLINE_CHANGE_CODE_UNITS) {
|
|
574
|
+
throw new FlexHarnessStoreFormatError(`Invalid content commitment at ${resolved.path}.`);
|
|
575
|
+
}
|
|
576
|
+
return root === undefined ? undefined : { revision: head.revision, contentRoot: root };
|
|
577
|
+
});
|
|
578
|
+
}
|
|
579
|
+
|
|
514
580
|
/**
|
|
515
581
|
* Saves a change to a log record while its head holds the expected revision. Only the head is
|
|
516
582
|
* read when the record takes the change; a compaction loads the record and checks the result in
|
|
@@ -532,8 +598,9 @@ export class FlexRecordStore {
|
|
|
532
598
|
const head = await this.findHead(resolved);
|
|
533
599
|
actualRevision = head?.revision ?? 0;
|
|
534
600
|
if (actualRevision !== change.expectedRevision) throw change.conflict(actualRevision);
|
|
535
|
-
|
|
536
|
-
|
|
601
|
+
const root = head ? committedLogRoot(head, resolved) : undefined;
|
|
602
|
+
if (head && root && this.takesChange(head, text)) {
|
|
603
|
+
if (await this.commitChange(resolved, head, revision, text, root)) return;
|
|
537
604
|
continue;
|
|
538
605
|
}
|
|
539
606
|
const stored = await this.loadLog(resolved, log);
|
|
@@ -881,10 +948,29 @@ export class FlexRecordStore {
|
|
|
881
948
|
for (let attempt = 0; attempt < chunkReadAttempts; attempt++) {
|
|
882
949
|
const head = await this.readHead(resolved);
|
|
883
950
|
const document = head.document;
|
|
884
|
-
if (!document
|
|
885
|
-
|
|
951
|
+
if (!document) return {};
|
|
952
|
+
const root = committedLogRoot(document, resolved);
|
|
953
|
+
if (head.text === undefined) {
|
|
954
|
+
if (document.contentRoot !== undefined && document.contentRoot !== null) {
|
|
955
|
+
throw new FlexHarnessStoreFormatError(`${resolved.path} has a log commitment without a base.`);
|
|
956
|
+
}
|
|
957
|
+
return { document };
|
|
958
|
+
}
|
|
959
|
+
if (!document.logId) {
|
|
960
|
+
if (document.contentRoot !== undefined && document.contentRoot !== null) {
|
|
961
|
+
throw new FlexHarnessStoreFormatError(`${resolved.path} has a log commitment without a log.`);
|
|
962
|
+
}
|
|
963
|
+
return { document, value: this.parse(resolved, head.text, log.validate) };
|
|
964
|
+
}
|
|
886
965
|
const changes = await this.readChanges(document);
|
|
887
966
|
if (changes) {
|
|
967
|
+
if (root !== undefined) {
|
|
968
|
+
let actualRoot = logBaseRoot(head.text);
|
|
969
|
+
for (const change of changes) actualRoot = logChangeRoot(actualRoot, change);
|
|
970
|
+
if (actualRoot !== root) {
|
|
971
|
+
throw new FlexHarnessStoreFormatError(`${resolved.path} has a mismatched log content commitment.`);
|
|
972
|
+
}
|
|
973
|
+
}
|
|
888
974
|
return { document, value: this.fold(resolved, document, head.text, changes, log) };
|
|
889
975
|
}
|
|
890
976
|
const latest = await this.findHead(resolved);
|
|
@@ -1007,6 +1093,8 @@ export class FlexRecordStore {
|
|
|
1007
1093
|
blobId,
|
|
1008
1094
|
chunkCount: chunked ? splitPayload(text).length : 0,
|
|
1009
1095
|
payloadSha256: chunked ? digest(text) : null,
|
|
1096
|
+
...(log ? { contentRoot: logBaseRoot(text) } : {}),
|
|
1097
|
+
...(log ? { contentRootRevision: write.revision, contentRootWriteToken: writeToken } : {}),
|
|
1010
1098
|
logId: log ? writeToken : null,
|
|
1011
1099
|
changeCount: 0,
|
|
1012
1100
|
recentChanges: [],
|
|
@@ -1015,6 +1103,7 @@ export class FlexRecordStore {
|
|
|
1015
1103
|
baseLength: log ? text.length : 0,
|
|
1016
1104
|
retiredLogId: current.logId ?? null,
|
|
1017
1105
|
},
|
|
1106
|
+
...(log ? {} : { $unset: { contentRoot: '', contentRootRevision: '', contentRootWriteToken: '' } }),
|
|
1018
1107
|
},
|
|
1019
1108
|
{ session: transaction },
|
|
1020
1109
|
));
|
|
@@ -1046,6 +1135,7 @@ export class FlexRecordStore {
|
|
|
1046
1135
|
head: FlexRecordDocument,
|
|
1047
1136
|
revision: number,
|
|
1048
1137
|
text: string,
|
|
1138
|
+
root: string,
|
|
1049
1139
|
): Promise<boolean> {
|
|
1050
1140
|
const recentLength = head.recentChanges.reduce((length, data) => length + data.length, 0);
|
|
1051
1141
|
const page = recentLength + text.length > FLEX_RECORD_INLINE_CHANGE_CODE_UNITS
|
|
@@ -1067,8 +1157,8 @@ export class FlexRecordStore {
|
|
|
1067
1157
|
const updated = await this.records.atomicUpdate(
|
|
1068
1158
|
{ recordId: resolved.recordId, writeToken: head.writeToken },
|
|
1069
1159
|
page
|
|
1070
|
-
? { $set: { revision, writeToken, recentChanges: [], lastPageId: page.pageId }, $inc: counts }
|
|
1071
|
-
: { $set: { revision, writeToken }, $inc: counts, $push: { recentChanges: text } },
|
|
1160
|
+
? { $set: { revision, writeToken, contentRoot: logChangeRoot(root, text), contentRootRevision: revision, contentRootWriteToken: writeToken, recentChanges: [], lastPageId: page.pageId }, $inc: counts }
|
|
1161
|
+
: { $set: { revision, writeToken, contentRoot: logChangeRoot(root, text), contentRootRevision: revision, contentRootWriteToken: writeToken }, $inc: counts, $push: { recentChanges: text } },
|
|
1072
1162
|
{ session: transaction },
|
|
1073
1163
|
);
|
|
1074
1164
|
if (updated.matchedCount === 1 && page) await this.changes.insert(page, { session: transaction });
|
|
@@ -1119,6 +1209,9 @@ export class FlexRecordStore {
|
|
|
1119
1209
|
head.blobId = chunk.blobId;
|
|
1120
1210
|
head.chunkCount = 1;
|
|
1121
1211
|
head.payloadSha256 = digest(text);
|
|
1212
|
+
head.contentRoot = logBaseRoot(text);
|
|
1213
|
+
head.contentRootRevision = revision;
|
|
1214
|
+
head.contentRootWriteToken = head.writeToken;
|
|
1122
1215
|
head.logId = head.writeToken;
|
|
1123
1216
|
head.baseLength = text.length;
|
|
1124
1217
|
} else {
|
|
@@ -56,6 +56,8 @@ All writes in one namespace now contend on its namespace document, not only crea
|
|
|
56
56
|
|
|
57
57
|
A projection and an Agent event history are each stored as a base plus the changes saved since. FlexHarness saves a projection as an `IFlexProjectionChange` and an Agent event history as an `IAgentEventChange`, which carry only the entries that changed, and the store appends the change to the record's head in the compare-and-swap that commits it, so a save reads and writes the head alone and costs the change rather than the whole session. The head holds the latest changes up to 16 Ki characters of JSON; the save that would exceed that first writes them, with its own change, as one page in `flexharness_changes`, and empties them in its swap. The base lives in chunks whatever its length, so the head each change swaps holds no payload; a session's first save creates the record together with a base of up to one chunk in one transaction. The changes are kept while together they stay no longer than the base, or than 64 Ki characters of JSON while the base is shorter, and no single change is longer than one chunk. The save that would exceed that compacts the record instead: it reads the record, applies the change, checks the resulting snapshot in full and writes it as the new base. The earlier base and its pages are removed like unreferenced chunks, by the record's next compaction, which finds those pages by their log instead of scanning the current one. A record therefore holds its base and changes no longer than it or that minimum, plus the earlier base and its pages until the next compaction. A session whose history shrank, after an undo branch for example, keeps its larger base until its changes outgrow it. A read applies every change to the base and checks the result in full, so it costs the base and every change since, and a record whose pages are incomplete fails with `FlexHarnessStoreFormatError`. A page a crashed writer left behind without swapping the head onto it is removed with the rest of its log, or by the record's deletion.
|
|
58
58
|
|
|
59
|
+
The projection store and each Agent event store also expose `loadHead`, an optional bounded read of `{ revision, contentRoot }`. A rooted log's head commits to its serialized base and ordered changes; each append advances that SHA-256 root and binds it to the new revision and write token in the head CAS. A full read verifies a current root. Missing and older unrooted logs return no head. An older writer that advances a rooted head but preserves fields it does not know leaves a well-formed stale binding: `loadHead` returns no root, and the next save validates and rewrites the whole log. Malformed commitment fields fail closed. This commitment does not certify a repaired session or replace recovery evidence.
|
|
60
|
+
|
|
59
61
|
A save of a scope, permission or job snapshot checks its expected revision against the record's head alone: it never reads the stored snapshot or its chunks, which it replaces whole. A projection or Agent event change checks it against the head in the same way and checks only its own form; the store reads the record only when it compacts. A record swap that loses to a concurrent writer is decided again against the newer record, up to eight times, with a bounded exponential backoff between attempts; a writer that still loses gets the domain's conflict error.
|
|
60
62
|
|
|
61
63
|
A projection or Agent event record that an earlier version wrote whole is read whole, and its next save rewrites it as a base. Versions before 12.0.0 cannot read a base: they fail closed on such a record with `FlexHarnessStoreFormatError` instead of reading the session without its changes, so rolling back to them is unsupported for every session 12.x has saved, as is running them beside 12.x on one database, and they leave the `flexharness_changes` documents in place.
|