@modelprofile.com/flexharness-agent 11.3.1 → 12.1.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_agent/classes.sessionengine.d.ts +9 -3
- package/dist_ts_agent/classes.sessionengine.js +58 -83
- package/dist_ts_agent/index.d.ts +2 -2
- package/dist_ts_agent/index.js +2 -2
- package/dist_ts_agent/persistence.file.d.ts +10 -8
- package/dist_ts_agent/persistence.file.js +18 -41
- package/dist_ts_agent/smartagent.interfaces.d.ts +5 -5
- package/dist_ts_agent/smartagent.persistence.d.ts +43 -40
- package/dist_ts_agent/smartagent.persistence.js +224 -145
- package/package.json +2 -2
- package/readme.md +7 -5
- package/ts_agent/classes.sessionengine.ts +61 -96
- package/ts_agent/index.ts +5 -9
- package/ts_agent/persistence.file.ts +25 -55
- package/ts_agent/readme.md +7 -5
- package/ts_agent/smartagent.interfaces.ts +5 -5
- package/ts_agent/smartagent.persistence.ts +269 -203
package/readme.md
CHANGED
|
@@ -282,7 +282,7 @@ The `review` callback belongs to your application. While awaiting acceptance, `c
|
|
|
282
282
|
|
|
283
283
|
`generate({ transaction, stop })` takes a second signal for the owner's stop, the way a user stops a turn. It ends the generation like `abort`, but the interrupted outcome records the stop (`stopped: true`, also accepted by `finalizeGeneration(transaction, 'interrupted', { stopped: true })` for a generation stopped after its execution completed). A stopped generation stays in future context once its model produced output: its prompt, the input it took in, the text its running model step streamed and the tool calls it issued. Each tool call without a recorded result is closed with an error result saying its effect is unknown, so the next request is well-formed for every provider. A generation stopped before any model output leaves no trace, so its prompt can be sent again without appearing twice. `isGenerationInModelContext(events, generationId)` applies the same rule to a list of events, for a caller that needs to know whether a finished generation stayed in context. Aborted and failed generations, and generations a restart interrupted, stay out of future context as before. `stop` requires a transactional generation.
|
|
284
284
|
|
|
285
|
-
Closing a session or restoring a stored session interrupts unfinished transactions. Restoration does not automatically rerun them. Persisted transactions require an
|
|
285
|
+
Closing a session or restoring a stored session interrupts unfinished transactions. Restoration does not automatically rerun them. Persisted transactions require an event store; without one, transactions are process-local.
|
|
286
286
|
|
|
287
287
|
A rejected generation does not roll back external tool effects. The runtime records transactional tool-execution intents and results. If a crash leaves an intent without a known result, inspect `listUncertainToolExecutions()` and reconcile the external operation through `reconcileToolExecution()` before treating its outcome as known. This is not a general exactly-once guarantee for external services.
|
|
288
288
|
|
|
@@ -319,17 +319,19 @@ Canonical events retain user and assistant messages, tool calls and results, run
|
|
|
319
319
|
Supply a stable `sessionId` and an event store to `AgentSession.create()`. It loads the stored snapshot and saves subsequent event changes. Do not use the constructor directly with a store, and do not also supply initial `events` or `messages` when a snapshot already exists.
|
|
320
320
|
|
|
321
321
|
```typescript
|
|
322
|
-
import type {
|
|
322
|
+
import type { IAgentEventStore } from '@modelprofile.com/flexharness-agent';
|
|
323
323
|
|
|
324
|
-
export function openStoredSession(eventStore:
|
|
324
|
+
export function openStoredSession(eventStore: IAgentEventStore, sessionId: string) {
|
|
325
325
|
return AgentSession.create({ ...setup, tools, eventStore, sessionId });
|
|
326
326
|
}
|
|
327
327
|
// The caller owns the returned session and must await session.close() when done.
|
|
328
328
|
```
|
|
329
329
|
|
|
330
|
-
Use an application-owned durable adapter for persistent sessions.
|
|
330
|
+
Use an application-owned durable adapter for persistent sessions. It implements `IAgentEventStore`: `load(sessionId)` returns the whole log as an `IAgentEventSnapshot` (schema version 2), and `save(sessionId, change, expectedRevision)` must atomically compare the revision, apply the `IAgentEventChange` and return the new revision, or reject a conflict. The change carries only what changed since the last save: `remove`, the IDs of events a context compaction archived; `replace`, events replaced by ID, such as a provisional tool result the model's response committed; and `append`, the events committed since, in order. `assertAgentEventChange()` checks a change's shape, `applyAgentEventChange()` applies it to a stored log, removals first, then replacements, then appends, and `validateAgentEventSnapshot()` checks the result; an adapter may also store the changes themselves and apply them when it loads. Preserve the schema and supported values in canonical events; the package exports `validateAgentEventSnapshot()`, `validateAgentEventArchive()` and `AgentEventStoreConflictError` for adapter implementations. Keep one active owner per session; compare-and-swap detects conflicting writes rather than merging competing sessions.
|
|
331
331
|
|
|
332
|
-
|
|
332
|
+
`AgentSession.create()` and `FileAgentEventStore` accept only schema-2 snapshots and archives. A schema-1 snapshot or archive, which versions before 12.0.0 read and rewrote as schema 2, fails closed: restoring it rejects instead of hydrating the session. `FileAgentEventStore` checks the snapshot each change makes in full before it writes it, so an invalid event fails its save.
|
|
333
|
+
|
|
334
|
+
Commits queued before a save starts share one durable change containing them all. An in-flight change is immutable, and every caller and change notification still waits for the save containing its event. The adapter's revision advances per durable change, not necessarily per event.
|
|
333
335
|
|
|
334
336
|
A tool's `toModelOutput` result is stored with its tool-result event and replayed to the model on later steps and turns. Content outputs may carry AI SDK v7 `file` parts, such as a rendered image: `{ type: 'content', value: [{ type: 'text', text }, { type: 'file', mediaType: 'image/png', data: { type: 'data', data: base64 } }] }`. The `data` union persists as `{ type: 'data', data }` with canonical base64 of at most `AGENT_TOOL_RESULT_FILE_MAX_BYTES` (20 MiB) decoded, `{ type: 'url', url }` with an absolute URL string, `{ type: 'reference', reference }` with provider file IDs, or `{ type: 'text', text }`. `mediaType` is a full IANA media type or its top-level segment. Binary data (`Uint8Array`, `Buffer`) and data URLs are not persistable; return base64. The schema validators reject any other shape, so a store that validates refuses the save.
|
|
335
337
|
|
|
@@ -58,10 +58,7 @@ import {
|
|
|
58
58
|
type TAgentToolCallFinishEvent,
|
|
59
59
|
type TAgentToolExecutionReconciliationOptions,
|
|
60
60
|
} from './smartagent.interfaces.js';
|
|
61
|
-
import {
|
|
62
|
-
isAgentEventStoreV2,
|
|
63
|
-
validateAgentEventSnapshotV2,
|
|
64
|
-
} from './smartagent.persistence.js';
|
|
61
|
+
import { validateAgentEventSnapshot } from './smartagent.persistence.js';
|
|
65
62
|
import { MAX_RETRY_ATTEMPTS, planModelCallRetry } from './smartagent.retry.js';
|
|
66
63
|
import { endModelStreamAtAbort } from './smartagent.modelabort.js';
|
|
67
64
|
import { AgentModelCallUsageRecorder } from './smartagent.usage.js';
|
|
@@ -69,9 +66,8 @@ import { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
|
|
|
69
66
|
import type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
|
|
70
67
|
import type {
|
|
71
68
|
IAgentEventArchive,
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
TAgentEventSnapshot,
|
|
69
|
+
IAgentEventChange,
|
|
70
|
+
IAgentEventSnapshot,
|
|
75
71
|
} from './smartagent.persistence.js';
|
|
76
72
|
import {
|
|
77
73
|
filterModelVisibleAgentEvents,
|
|
@@ -81,13 +77,6 @@ import {
|
|
|
81
77
|
type IAgentGenerationTransaction,
|
|
82
78
|
} from './smartagent.transactions.js';
|
|
83
79
|
|
|
84
|
-
const isTransactionalControlEvent = (event: TAgentEvent): boolean =>
|
|
85
|
-
event.type === 'generation-begun'
|
|
86
|
-
|| event.type === 'generation-execution-started'
|
|
87
|
-
|| event.type === 'generation-execution-completed'
|
|
88
|
-
|| event.type === 'generation-outcome'
|
|
89
|
-
|| event.type === 'tool-execution-intent'
|
|
90
|
-
|| event.type === 'tool-execution-reconciliation';
|
|
91
80
|
|
|
92
81
|
interface IToolCallPreparationLedgerEntry {
|
|
93
82
|
signature: string;
|
|
@@ -172,7 +161,9 @@ interface IGenerationLeaseCleanupOwnership {
|
|
|
172
161
|
settled: boolean;
|
|
173
162
|
}
|
|
174
163
|
|
|
175
|
-
const sessionHydrations = new WeakMap<IAgentSessionOptions,
|
|
164
|
+
const sessionHydrations = new WeakMap<IAgentSessionOptions, IAgentEventSnapshot | undefined>();
|
|
165
|
+
|
|
166
|
+
const createEmptyEventChange = (): IAgentEventChange => ({ remove: [], replace: [], append: [] });
|
|
176
167
|
|
|
177
168
|
const sleep = async (milliseconds: number, signal?: AbortSignal): Promise<void> =>
|
|
178
169
|
new Promise((resolve, reject) => {
|
|
@@ -352,7 +343,10 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
352
343
|
private sequence = 0;
|
|
353
344
|
private persistenceRevision = 0;
|
|
354
345
|
private persistenceQueue: Promise<void> = Promise.resolve();
|
|
355
|
-
|
|
346
|
+
/** What the log gained since the last save began, in clones the engine never mutates. */
|
|
347
|
+
private unsavedChange = createEmptyEventChange();
|
|
348
|
+
/** The queued save that has not begun; it takes `unsavedChange` when it begins. */
|
|
349
|
+
private pendingPersistence?: Promise<void>;
|
|
356
350
|
private persistenceError: unknown;
|
|
357
351
|
private readonly notificationDispatches = new Set<Promise<void>>();
|
|
358
352
|
private readonly listeners = new Map<TAgentSessionChangeListener, IAgentSessionListenerState>();
|
|
@@ -386,23 +380,8 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
386
380
|
if (!options.sessionId?.trim()) {
|
|
387
381
|
throw new Error('AgentSession.create() requires sessionId when eventStore is configured.');
|
|
388
382
|
}
|
|
389
|
-
|
|
390
|
-
const
|
|
391
|
-
if (
|
|
392
|
-
snapshot
|
|
393
|
-
&& ((!v2Store && snapshot.schemaVersion !== 1)
|
|
394
|
-
|| (v2Store && snapshot.schemaVersion !== 1 && snapshot.schemaVersion !== 2))
|
|
395
|
-
) {
|
|
396
|
-
throw new Error(
|
|
397
|
-
`Unsupported agent event snapshot schema version ${String((snapshot as { schemaVersion?: unknown }).schemaVersion)}.`,
|
|
398
|
-
);
|
|
399
|
-
}
|
|
400
|
-
if (!v2Store && snapshot?.events.some(isTransactionalControlEvent)) {
|
|
401
|
-
throw new Error('Transactional events require an IAgentEventStoreV2-capable event store.');
|
|
402
|
-
}
|
|
403
|
-
if (snapshot?.schemaVersion === 2) {
|
|
404
|
-
snapshot = validateAgentEventSnapshotV2(snapshot, options.sessionId);
|
|
405
|
-
}
|
|
383
|
+
const stored = await options.eventStore.load(options.sessionId);
|
|
384
|
+
const snapshot = stored && validateAgentEventSnapshot(stored, options.sessionId);
|
|
406
385
|
sessionHydrations.set(options, snapshot);
|
|
407
386
|
let session: TSession;
|
|
408
387
|
try {
|
|
@@ -492,13 +471,6 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
492
471
|
if (hydrationSnapshot && initialEvents.length > 0) {
|
|
493
472
|
throw new Error('Persisted sessions cannot also receive initial events or messages.');
|
|
494
473
|
}
|
|
495
|
-
if (
|
|
496
|
-
options.eventStore
|
|
497
|
-
&& !isAgentEventStoreV2(options.eventStore)
|
|
498
|
-
&& initialEvents.some(isTransactionalControlEvent)
|
|
499
|
-
) {
|
|
500
|
-
throw new Error('Transactional events require an IAgentEventStoreV2-capable event store.');
|
|
501
|
-
}
|
|
502
474
|
for (const event of initialEvents) this.commitEvent(event, false);
|
|
503
475
|
if (options.eventStore && (!hydrationSnapshot || initialEvents.length > 0)) {
|
|
504
476
|
this.queuePersistence();
|
|
@@ -587,31 +559,54 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
587
559
|
|
|
588
560
|
private queuePersistence(): Promise<void> {
|
|
589
561
|
if (!this.options.eventStore) return Promise.resolve();
|
|
590
|
-
|
|
591
|
-
if (this.pendingPersistence) {
|
|
592
|
-
this.pendingPersistence.snapshot = snapshot;
|
|
593
|
-
return this.pendingPersistence.task;
|
|
594
|
-
}
|
|
595
|
-
let pending: NonNullable<AgentSessionEngine['pendingPersistence']>;
|
|
562
|
+
if (this.pendingPersistence) return this.pendingPersistence;
|
|
596
563
|
const operation = this.persistenceQueue.then(async () => {
|
|
597
|
-
|
|
564
|
+
this.pendingPersistence = undefined;
|
|
598
565
|
if (this.persistenceError !== undefined) throw this.persistenceError;
|
|
566
|
+
const change = this.unsavedChange;
|
|
567
|
+
this.unsavedChange = createEmptyEventChange();
|
|
599
568
|
this.persistenceRevision = await this.options.eventStore!.save(
|
|
600
569
|
this.options.sessionId!,
|
|
601
|
-
|
|
570
|
+
change,
|
|
602
571
|
this.persistenceRevision,
|
|
603
572
|
);
|
|
604
573
|
});
|
|
605
|
-
// One
|
|
606
|
-
//
|
|
607
|
-
|
|
608
|
-
this.pendingPersistence =
|
|
574
|
+
// One save carries every change recorded before it begins, and callers still wait for the
|
|
575
|
+
// save that contains their change. A failed save ends persistence for the session, so the
|
|
576
|
+
// next save always continues from the stored log the last one left.
|
|
577
|
+
this.pendingPersistence = operation;
|
|
609
578
|
this.persistenceQueue = operation.catch((error) => {
|
|
610
579
|
this.persistenceError ??= error;
|
|
611
580
|
});
|
|
612
581
|
return operation;
|
|
613
582
|
}
|
|
614
583
|
|
|
584
|
+
/** Records a stored event's replacement for the next save. */
|
|
585
|
+
private recordReplacement(event: TAgentEvent): void {
|
|
586
|
+
const persisted = structuredClone(event);
|
|
587
|
+
const change = this.unsavedChange;
|
|
588
|
+
const appendIndex = change.append.findIndex((entry) => entry.id === event.id);
|
|
589
|
+
if (appendIndex >= 0) {
|
|
590
|
+
change.append[appendIndex] = persisted;
|
|
591
|
+
return;
|
|
592
|
+
}
|
|
593
|
+
const replaceIndex = change.replace.findIndex((entry) => entry.id === event.id);
|
|
594
|
+
if (replaceIndex >= 0) change.replace[replaceIndex] = persisted;
|
|
595
|
+
else change.replace.push(persisted);
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
/** Records the removal of stored events for the next save. */
|
|
599
|
+
private recordRemoval(eventIds: readonly string[]): void {
|
|
600
|
+
const removed = new Set(eventIds);
|
|
601
|
+
const change = this.unsavedChange;
|
|
602
|
+
const unsaved = new Set(change.append.map((event) => event.id));
|
|
603
|
+
change.append = change.append.filter((event) => !removed.has(event.id));
|
|
604
|
+
change.replace = change.replace.filter((event) => !removed.has(event.id));
|
|
605
|
+
for (const eventId of eventIds) {
|
|
606
|
+
if (!unsaved.has(eventId)) change.remove.push(eventId);
|
|
607
|
+
}
|
|
608
|
+
}
|
|
609
|
+
|
|
615
610
|
private async flushPersistence(): Promise<void> {
|
|
616
611
|
await this.persistenceQueue;
|
|
617
612
|
if (this.persistenceError !== undefined) throw this.persistenceError;
|
|
@@ -719,11 +714,16 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
719
714
|
}
|
|
720
715
|
nextIds.add(event.id);
|
|
721
716
|
}
|
|
722
|
-
|
|
717
|
+
const persistedEvents = this.options.eventStore ? structuredClone(events) : undefined;
|
|
723
718
|
const committedEvents = events.map((event) => ({
|
|
724
719
|
...event,
|
|
725
720
|
sequence: ++this.sequence,
|
|
726
721
|
}) as TEvent);
|
|
722
|
+
if (persistedEvents) {
|
|
723
|
+
for (const [index, event] of persistedEvents.entries()) {
|
|
724
|
+
this.unsavedChange.append.push({ ...event, sequence: committedEvents[index].sequence });
|
|
725
|
+
}
|
|
726
|
+
}
|
|
727
727
|
for (const event of committedEvents) {
|
|
728
728
|
this.events.push(event);
|
|
729
729
|
this.eventIds.add(event.id);
|
|
@@ -746,15 +746,6 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
746
746
|
if (this.closed) return Promise.reject(new Error('AgentSession is closed.'));
|
|
747
747
|
if (this.persistenceError !== undefined) return Promise.reject(this.persistenceError);
|
|
748
748
|
if (this.maintenanceError !== undefined) return Promise.reject(this.maintenanceError);
|
|
749
|
-
if (
|
|
750
|
-
isTransactionalControlEvent(event)
|
|
751
|
-
&& this.options.eventStore
|
|
752
|
-
&& !isAgentEventStoreV2(this.options.eventStore)
|
|
753
|
-
) {
|
|
754
|
-
return Promise.reject(
|
|
755
|
-
new Error('Transactional events require an IAgentEventStoreV2-capable event store.'),
|
|
756
|
-
);
|
|
757
|
-
}
|
|
758
749
|
this.commitEvent(event);
|
|
759
750
|
return this.flushPersistence().then(async () => {
|
|
760
751
|
this.scheduleEventRetention();
|
|
@@ -852,18 +843,10 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
852
843
|
await this.flushPersistence();
|
|
853
844
|
}
|
|
854
845
|
|
|
855
|
-
private transactionalStoreCapabilityError(): Error | undefined {
|
|
856
|
-
return this.options.eventStore && !isAgentEventStoreV2(this.options.eventStore)
|
|
857
|
-
? new Error('Transactional generations require an IAgentEventStoreV2-capable event store.')
|
|
858
|
-
: undefined;
|
|
859
|
-
}
|
|
860
|
-
|
|
861
846
|
public beginGeneration(
|
|
862
847
|
content: TAgentPrompt,
|
|
863
848
|
options: IAgentBeginGenerationOptions = {},
|
|
864
849
|
): Promise<IAgentGenerationHandle> {
|
|
865
|
-
const capabilityError = this.transactionalStoreCapabilityError();
|
|
866
|
-
if (capabilityError) return Promise.reject(capabilityError);
|
|
867
850
|
return this.queueExclusive(async () => {
|
|
868
851
|
await this.flushPersistence();
|
|
869
852
|
const generationId = options.generationId ?? createAgentEventId('generation');
|
|
@@ -979,8 +962,6 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
979
962
|
outcome: TAgentGenerationOutcome,
|
|
980
963
|
options: IAgentFinalizeGenerationOptions = {},
|
|
981
964
|
): Promise<void> {
|
|
982
|
-
const capabilityError = this.transactionalStoreCapabilityError();
|
|
983
|
-
if (capabilityError) return Promise.reject(capabilityError);
|
|
984
965
|
return this.queueExclusive(async () => {
|
|
985
966
|
if (!['accepted', 'rejected', 'interrupted'].includes(outcome)) {
|
|
986
967
|
throw new Error(`Invalid transactional generation outcome "${String(outcome)}".`);
|
|
@@ -1024,8 +1005,6 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1024
1005
|
intentId: string,
|
|
1025
1006
|
reconciliation: TAgentToolExecutionReconciliationOptions,
|
|
1026
1007
|
): Promise<void> {
|
|
1027
|
-
const capabilityError = this.transactionalStoreCapabilityError();
|
|
1028
|
-
if (capabilityError) return Promise.reject(capabilityError);
|
|
1029
1008
|
return this.queueExclusive(async () => {
|
|
1030
1009
|
await this.flushPersistence();
|
|
1031
1010
|
const intent = this.events.find((event): event is IToolExecutionIntentEvent =>
|
|
@@ -1144,10 +1123,6 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1144
1123
|
|
|
1145
1124
|
public scheduleGenerate(options: IAgentScheduleGenerateOptions): Promise<IAgentGenerateResult> {
|
|
1146
1125
|
if (this.closed) return Promise.reject(new Error('AgentSession is closed.'));
|
|
1147
|
-
const capabilityError = options.transaction
|
|
1148
|
-
? this.transactionalStoreCapabilityError()
|
|
1149
|
-
: undefined;
|
|
1150
|
-
if (capabilityError) return Promise.reject(capabilityError);
|
|
1151
1126
|
if (options.stop && !options.transaction) {
|
|
1152
1127
|
return Promise.reject(new Error('A stop signal requires a transactional generation.'));
|
|
1153
1128
|
}
|
|
@@ -1456,13 +1431,13 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1456
1431
|
|
|
1457
1432
|
public archiveCompactedEvents(
|
|
1458
1433
|
compactionEventId?: string,
|
|
1459
|
-
): Promise<
|
|
1434
|
+
): Promise<IAgentEventArchive | undefined> {
|
|
1460
1435
|
return this.queueExclusive(() => this.archiveCompactedEventsLocked(compactionEventId));
|
|
1461
1436
|
}
|
|
1462
1437
|
|
|
1463
1438
|
private async archiveCompactedEventsLocked(
|
|
1464
1439
|
compactionEventId?: string,
|
|
1465
|
-
): Promise<
|
|
1440
|
+
): Promise<IAgentEventArchive | undefined> {
|
|
1466
1441
|
if (getOpenAgentGenerationTransactions(this.events).length > 0) {
|
|
1467
1442
|
throw new Error('Archival is blocked while a transactional generation is open.');
|
|
1468
1443
|
}
|
|
@@ -1480,27 +1455,20 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1480
1455
|
const coveredIds = new Set(compaction.coveredEventIds);
|
|
1481
1456
|
const archivedEvents = this.events.filter((event) => coveredIds.has(event.id));
|
|
1482
1457
|
if (archivedEvents.length === 0) {
|
|
1483
|
-
return
|
|
1484
|
-
? eventStore.loadArchive?.(this.options.sessionId!, compaction.id)
|
|
1485
|
-
: eventStore.loadArchive?.(this.options.sessionId!, compaction.id);
|
|
1458
|
+
return eventStore.loadArchive?.(this.options.sessionId!, compaction.id);
|
|
1486
1459
|
}
|
|
1487
|
-
const
|
|
1460
|
+
const archive: IAgentEventArchive = {
|
|
1461
|
+
schemaVersion: 2,
|
|
1488
1462
|
sessionId: this.options.sessionId!,
|
|
1489
1463
|
archiveId: compaction.id,
|
|
1490
1464
|
createdAt: Date.now(),
|
|
1491
1465
|
events: structuredClone(archivedEvents),
|
|
1492
1466
|
};
|
|
1493
|
-
const archive: TAgentEventArchive = isAgentEventStoreV2(eventStore)
|
|
1494
|
-
? { ...archiveBase, schemaVersion: 2 }
|
|
1495
|
-
: { ...archiveBase, schemaVersion: 1 };
|
|
1496
1467
|
await this.flushPersistence();
|
|
1497
|
-
|
|
1498
|
-
await eventStore.archive?.(archive as IAgentEventArchiveV2);
|
|
1499
|
-
} else {
|
|
1500
|
-
await eventStore.archive?.(archive as IAgentEventArchive);
|
|
1501
|
-
}
|
|
1468
|
+
await eventStore.archive(archive);
|
|
1502
1469
|
this.events.splice(0, this.events.length, ...this.events.filter((event) => !coveredIds.has(event.id)));
|
|
1503
1470
|
for (const event of archivedEvents) this.eventIds.delete(event.id);
|
|
1471
|
+
this.recordRemoval(archivedEvents.map((event) => event.id));
|
|
1504
1472
|
const durability = this.queuePersistence();
|
|
1505
1473
|
this.queueNotification({ type: 'archived', events: archivedEvents }, durability);
|
|
1506
1474
|
await durability;
|
|
@@ -1609,6 +1577,7 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1609
1577
|
messageProviderOptions: modelEvent.messageProviderOptions,
|
|
1610
1578
|
};
|
|
1611
1579
|
const updatedEvent = this.events[provisionalIndex];
|
|
1580
|
+
if (this.options.eventStore) this.recordReplacement(updatedEvent);
|
|
1612
1581
|
const durability = this.queuePersistence();
|
|
1613
1582
|
this.queueNotification({ type: 'updated', events: [updatedEvent] }, durability);
|
|
1614
1583
|
}
|
|
@@ -1953,10 +1922,6 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1953
1922
|
}
|
|
1954
1923
|
|
|
1955
1924
|
public generate(options: IAgentGenerateOptions = {}): Promise<IAgentGenerateResult> {
|
|
1956
|
-
const capabilityError = options.transaction
|
|
1957
|
-
? this.transactionalStoreCapabilityError()
|
|
1958
|
-
: undefined;
|
|
1959
|
-
if (capabilityError) return Promise.reject(capabilityError);
|
|
1960
1925
|
if (options.stop && !options.transaction) {
|
|
1961
1926
|
return Promise.reject(new Error('A stop signal requires a transactional generation.'));
|
|
1962
1927
|
}
|
package/ts_agent/index.ts
CHANGED
|
@@ -36,10 +36,11 @@ export {
|
|
|
36
36
|
export {
|
|
37
37
|
AGENT_TOOL_RESULT_FILE_MAX_BYTES,
|
|
38
38
|
AgentEventStoreConflictError,
|
|
39
|
+
applyAgentEventChange,
|
|
40
|
+
assertAgentEventChange,
|
|
39
41
|
InMemoryAgentEventStore,
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
validateAgentEventSnapshotV2,
|
|
42
|
+
validateAgentEventArchive,
|
|
43
|
+
validateAgentEventSnapshot,
|
|
43
44
|
} from './smartagent.persistence.js';
|
|
44
45
|
export type {
|
|
45
46
|
IAgentCacheOptions,
|
|
@@ -87,14 +88,9 @@ export type {
|
|
|
87
88
|
} from './smartagent.interfaces.js';
|
|
88
89
|
export type {
|
|
89
90
|
IAgentEventArchive,
|
|
90
|
-
|
|
91
|
+
IAgentEventChange,
|
|
91
92
|
IAgentEventSnapshot,
|
|
92
|
-
IAgentEventSnapshotV2,
|
|
93
93
|
IAgentEventStore,
|
|
94
|
-
IAgentEventStoreV2,
|
|
95
|
-
TAgentEventArchive,
|
|
96
|
-
TAgentEventSnapshot,
|
|
97
|
-
TAgentEventStore,
|
|
98
94
|
} from './smartagent.persistence.js';
|
|
99
95
|
export type {
|
|
100
96
|
IAgentEventBase,
|
|
@@ -1,15 +1,10 @@
|
|
|
1
1
|
import * as plugins from './plugins.node.js';
|
|
2
|
-
import type { TAgentEvent } from './smartagent.events.js';
|
|
3
2
|
import {
|
|
4
|
-
AgentEventStoreConflictError, clone,
|
|
5
|
-
|
|
6
|
-
type
|
|
7
|
-
type TAgentEventArchive, type TAgentEventSnapshot,
|
|
3
|
+
AgentEventStoreConflictError, clone, createChangedSnapshot,
|
|
4
|
+
validateAgentEventArchive, validateAgentEventSnapshot,
|
|
5
|
+
type IAgentEventArchive, type IAgentEventChange, type IAgentEventSnapshot, type IAgentEventStore,
|
|
8
6
|
} from './smartagent.persistence.js';
|
|
9
7
|
|
|
10
|
-
const SNAPSHOT_SCHEMA_VERSION = 2 as const;
|
|
11
|
-
const ARCHIVE_SCHEMA_VERSION = 2 as const;
|
|
12
|
-
|
|
13
8
|
export interface IFileAgentEventStoreOptions {
|
|
14
9
|
rootDir: string;
|
|
15
10
|
/** Maximum time spent waiting for another writer. Default: 10 seconds. */
|
|
@@ -20,59 +15,35 @@ const assertSessionId = (sessionId: string): void => {
|
|
|
20
15
|
if (!sessionId.trim()) throw new Error('Agent event store sessionId must not be empty.');
|
|
21
16
|
};
|
|
22
17
|
|
|
23
|
-
const decodeSnapshot = (value: unknown, sessionId: string):
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
return validateAgentEventSnapshotV2(value, sessionId);
|
|
28
|
-
} catch {
|
|
29
|
-
throw new Error(`Invalid agent event snapshot for session "${sessionId}".`);
|
|
30
|
-
}
|
|
31
|
-
}
|
|
32
|
-
if (
|
|
33
|
-
!snapshot
|
|
34
|
-
|| snapshot.schemaVersion !== 1
|
|
35
|
-
|| snapshot.sessionId !== sessionId
|
|
36
|
-
|| !Number.isSafeInteger(snapshot.revision)
|
|
37
|
-
|| (snapshot.revision ?? -1) < 1
|
|
38
|
-
|| !Array.isArray(snapshot.events)
|
|
39
|
-
) {
|
|
18
|
+
const decodeSnapshot = (value: unknown, sessionId: string): IAgentEventSnapshot => {
|
|
19
|
+
try {
|
|
20
|
+
return validateAgentEventSnapshot(value, sessionId);
|
|
21
|
+
} catch {
|
|
40
22
|
throw new Error(`Invalid agent event snapshot for session "${sessionId}".`);
|
|
41
23
|
}
|
|
42
|
-
return snapshot as TAgentEventSnapshot;
|
|
43
24
|
};
|
|
44
25
|
|
|
45
26
|
const decodeArchive = (
|
|
46
27
|
value: unknown,
|
|
47
28
|
sessionId: string,
|
|
48
29
|
archiveId: string,
|
|
49
|
-
):
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
return validateAgentEventArchiveV2(value, sessionId, archiveId);
|
|
54
|
-
} catch {
|
|
55
|
-
throw new Error(`Invalid agent event archive "${archiveId}" for session "${sessionId}".`);
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
if (
|
|
59
|
-
!archive
|
|
60
|
-
|| archive.schemaVersion !== 1
|
|
61
|
-
|| archive.sessionId !== sessionId
|
|
62
|
-
|| archive.archiveId !== archiveId
|
|
63
|
-
|| !Array.isArray(archive.events)
|
|
64
|
-
) {
|
|
30
|
+
): IAgentEventArchive => {
|
|
31
|
+
try {
|
|
32
|
+
return validateAgentEventArchive(value, sessionId, archiveId);
|
|
33
|
+
} catch {
|
|
65
34
|
throw new Error(`Invalid agent event archive "${archiveId}" for session "${sessionId}".`);
|
|
66
35
|
}
|
|
67
|
-
return archive as TAgentEventArchive;
|
|
68
36
|
};
|
|
69
37
|
|
|
70
38
|
const sleep = async (milliseconds: number): Promise<void> => {
|
|
71
39
|
await new Promise((resolve) => setTimeout(resolve, milliseconds));
|
|
72
40
|
};
|
|
73
41
|
|
|
74
|
-
|
|
75
|
-
|
|
42
|
+
/**
|
|
43
|
+
* Stores each session's event log in one file. A save reads the file, applies the change and
|
|
44
|
+
* writes the whole log again, so its cost grows with the log.
|
|
45
|
+
*/
|
|
46
|
+
export class FileAgentEventStore implements IAgentEventStore {
|
|
76
47
|
private readonly rootDir: string;
|
|
77
48
|
private readonly lockTimeoutMs: number;
|
|
78
49
|
|
|
@@ -179,32 +150,31 @@ export class FileAgentEventStore implements IAgentEventStoreV2 {
|
|
|
179
150
|
}
|
|
180
151
|
}
|
|
181
152
|
|
|
182
|
-
public async load(sessionId: string): Promise<
|
|
153
|
+
public async load(sessionId: string): Promise<IAgentEventSnapshot | undefined> {
|
|
183
154
|
const value = await this.readValue(this.snapshotPath(sessionId));
|
|
184
155
|
return value === undefined ? undefined : decodeSnapshot(value, sessionId);
|
|
185
156
|
}
|
|
186
157
|
|
|
187
158
|
public async save(
|
|
188
159
|
sessionId: string,
|
|
189
|
-
|
|
160
|
+
change: IAgentEventChange,
|
|
190
161
|
expectedRevision: number,
|
|
191
162
|
): Promise<number> {
|
|
192
163
|
return this.withSessionLock(sessionId, async () => {
|
|
193
164
|
const filePath = this.snapshotPath(sessionId);
|
|
194
165
|
const currentValue = await this.readValue(filePath);
|
|
195
|
-
const
|
|
196
|
-
|
|
197
|
-
: decodeSnapshot(currentValue, sessionId).revision;
|
|
166
|
+
const current = currentValue === undefined ? undefined : decodeSnapshot(currentValue, sessionId);
|
|
167
|
+
const actualRevision = current?.revision ?? 0;
|
|
198
168
|
if (actualRevision !== expectedRevision) {
|
|
199
169
|
throw new AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
|
|
200
170
|
}
|
|
201
|
-
const
|
|
202
|
-
await this.writeAtomic(filePath,
|
|
203
|
-
return revision;
|
|
171
|
+
const snapshot = createChangedSnapshot(sessionId, current, change);
|
|
172
|
+
await this.writeAtomic(filePath, snapshot);
|
|
173
|
+
return snapshot.revision;
|
|
204
174
|
});
|
|
205
175
|
}
|
|
206
176
|
|
|
207
|
-
public async archive(archive:
|
|
177
|
+
public async archive(archive: IAgentEventArchive): Promise<void> {
|
|
208
178
|
const nextArchive = clone(archive);
|
|
209
179
|
await this.withSessionLock(archive.sessionId, async () => {
|
|
210
180
|
const filePath = this.archivePath(archive.sessionId, archive.archiveId);
|
|
@@ -225,7 +195,7 @@ export class FileAgentEventStore implements IAgentEventStoreV2 {
|
|
|
225
195
|
public async loadArchive(
|
|
226
196
|
sessionId: string,
|
|
227
197
|
archiveId: string,
|
|
228
|
-
): Promise<
|
|
198
|
+
): Promise<IAgentEventArchive | undefined> {
|
|
229
199
|
const value = await this.readValue(this.archivePath(sessionId, archiveId));
|
|
230
200
|
return value === undefined ? undefined : decodeArchive(value, sessionId, archiveId);
|
|
231
201
|
}
|
package/ts_agent/readme.md
CHANGED
|
@@ -282,7 +282,7 @@ The `review` callback belongs to your application. While awaiting acceptance, `c
|
|
|
282
282
|
|
|
283
283
|
`generate({ transaction, stop })` takes a second signal for the owner's stop, the way a user stops a turn. It ends the generation like `abort`, but the interrupted outcome records the stop (`stopped: true`, also accepted by `finalizeGeneration(transaction, 'interrupted', { stopped: true })` for a generation stopped after its execution completed). A stopped generation stays in future context once its model produced output: its prompt, the input it took in, the text its running model step streamed and the tool calls it issued. Each tool call without a recorded result is closed with an error result saying its effect is unknown, so the next request is well-formed for every provider. A generation stopped before any model output leaves no trace, so its prompt can be sent again without appearing twice. `isGenerationInModelContext(events, generationId)` applies the same rule to a list of events, for a caller that needs to know whether a finished generation stayed in context. Aborted and failed generations, and generations a restart interrupted, stay out of future context as before. `stop` requires a transactional generation.
|
|
284
284
|
|
|
285
|
-
Closing a session or restoring a stored session interrupts unfinished transactions. Restoration does not automatically rerun them. Persisted transactions require an
|
|
285
|
+
Closing a session or restoring a stored session interrupts unfinished transactions. Restoration does not automatically rerun them. Persisted transactions require an event store; without one, transactions are process-local.
|
|
286
286
|
|
|
287
287
|
A rejected generation does not roll back external tool effects. The runtime records transactional tool-execution intents and results. If a crash leaves an intent without a known result, inspect `listUncertainToolExecutions()` and reconcile the external operation through `reconcileToolExecution()` before treating its outcome as known. This is not a general exactly-once guarantee for external services.
|
|
288
288
|
|
|
@@ -319,17 +319,19 @@ Canonical events retain user and assistant messages, tool calls and results, run
|
|
|
319
319
|
Supply a stable `sessionId` and an event store to `AgentSession.create()`. It loads the stored snapshot and saves subsequent event changes. Do not use the constructor directly with a store, and do not also supply initial `events` or `messages` when a snapshot already exists.
|
|
320
320
|
|
|
321
321
|
```typescript
|
|
322
|
-
import type {
|
|
322
|
+
import type { IAgentEventStore } from '@modelprofile.com/flexharness-agent';
|
|
323
323
|
|
|
324
|
-
export function openStoredSession(eventStore:
|
|
324
|
+
export function openStoredSession(eventStore: IAgentEventStore, sessionId: string) {
|
|
325
325
|
return AgentSession.create({ ...setup, tools, eventStore, sessionId });
|
|
326
326
|
}
|
|
327
327
|
// The caller owns the returned session and must await session.close() when done.
|
|
328
328
|
```
|
|
329
329
|
|
|
330
|
-
Use an application-owned durable adapter for persistent sessions.
|
|
330
|
+
Use an application-owned durable adapter for persistent sessions. It implements `IAgentEventStore`: `load(sessionId)` returns the whole log as an `IAgentEventSnapshot` (schema version 2), and `save(sessionId, change, expectedRevision)` must atomically compare the revision, apply the `IAgentEventChange` and return the new revision, or reject a conflict. The change carries only what changed since the last save: `remove`, the IDs of events a context compaction archived; `replace`, events replaced by ID, such as a provisional tool result the model's response committed; and `append`, the events committed since, in order. `assertAgentEventChange()` checks a change's shape, `applyAgentEventChange()` applies it to a stored log, removals first, then replacements, then appends, and `validateAgentEventSnapshot()` checks the result; an adapter may also store the changes themselves and apply them when it loads. Preserve the schema and supported values in canonical events; the package exports `validateAgentEventSnapshot()`, `validateAgentEventArchive()` and `AgentEventStoreConflictError` for adapter implementations. Keep one active owner per session; compare-and-swap detects conflicting writes rather than merging competing sessions.
|
|
331
331
|
|
|
332
|
-
|
|
332
|
+
`AgentSession.create()` and `FileAgentEventStore` accept only schema-2 snapshots and archives. A schema-1 snapshot or archive, which versions before 12.0.0 read and rewrote as schema 2, fails closed: restoring it rejects instead of hydrating the session. `FileAgentEventStore` checks the snapshot each change makes in full before it writes it, so an invalid event fails its save.
|
|
333
|
+
|
|
334
|
+
Commits queued before a save starts share one durable change containing them all. An in-flight change is immutable, and every caller and change notification still waits for the save containing its event. The adapter's revision advances per durable change, not necessarily per event.
|
|
333
335
|
|
|
334
336
|
A tool's `toModelOutput` result is stored with its tool-result event and replayed to the model on later steps and turns. Content outputs may carry AI SDK v7 `file` parts, such as a rendered image: `{ type: 'content', value: [{ type: 'text', text }, { type: 'file', mediaType: 'image/png', data: { type: 'data', data: base64 } }] }`. The `data` union persists as `{ type: 'data', data }` with canonical base64 of at most `AGENT_TOOL_RESULT_FILE_MAX_BYTES` (20 MiB) decoded, `{ type: 'url', url }` with an absolute URL string, `{ type: 'reference', reference }` with provider file IDs, or `{ type: 'text', text }`. `mediaType` is a full IANA media type or its top-level segment. Binary data (`Uint8Array`, `Buffer`) and data URLs are not persistable; return base64. The schema validators reject any other shape, so a store that validates refuses the save.
|
|
335
337
|
|
|
@@ -17,7 +17,7 @@ import type {
|
|
|
17
17
|
TAgentGenerationOutcome,
|
|
18
18
|
TAgentToolResultOutput,
|
|
19
19
|
} from './smartagent.events.js';
|
|
20
|
-
import type {
|
|
20
|
+
import type { IAgentEventArchive, IAgentEventStore } from './smartagent.persistence.js';
|
|
21
21
|
import type { AgentPendingInputQueue, IAgentAppliedInput } from './smartagent.pendinginput.js';
|
|
22
22
|
import type { IAgentRetryEvent } from './smartagent.retry.js';
|
|
23
23
|
|
|
@@ -221,8 +221,8 @@ export interface IAgentSessionOptions {
|
|
|
221
221
|
providerOptions?: ProviderOptions;
|
|
222
222
|
/** Stable session id used as provider prompt-cache affinity key where supported. */
|
|
223
223
|
sessionId?: string;
|
|
224
|
-
/** Optional event store.
|
|
225
|
-
eventStore?:
|
|
224
|
+
/** Optional event store. Each commit is saved to it as a change to the stored log. */
|
|
225
|
+
eventStore?: IAgentEventStore;
|
|
226
226
|
/** Prompt-cache policy. Default: 'auto'. Set false to disable smartagent cache defaults. */
|
|
227
227
|
cache?: TAgentCacheSetting;
|
|
228
228
|
/**
|
|
@@ -443,7 +443,7 @@ export interface IAgentGenerateOptions {
|
|
|
443
443
|
/**
|
|
444
444
|
* Optionally acquires generation-scoped resources in transactional or legacy mode.
|
|
445
445
|
* Called at most once, only if execution reaches preparation. Persisted transactions
|
|
446
|
-
* have durable
|
|
446
|
+
* have durable execution authority first; legacy/process-local calls do not.
|
|
447
447
|
* The callback owns cleanup of partial acquisition if it throws before returning a lease.
|
|
448
448
|
*/
|
|
449
449
|
prepare?: TAgentGenerationPrepare;
|
|
@@ -556,7 +556,7 @@ export interface IAgentSession {
|
|
|
556
556
|
scheduleGenerate(options: IAgentScheduleGenerateOptions): Promise<IAgentGenerateResult>;
|
|
557
557
|
cancelScheduledGeneration(key: string, reason?: unknown): boolean;
|
|
558
558
|
compact(options?: IAgentCompactOptions): Promise<void>;
|
|
559
|
-
archiveCompactedEvents(compactionEventId?: string): Promise<
|
|
559
|
+
archiveCompactedEvents(compactionEventId?: string): Promise<IAgentEventArchive | undefined>;
|
|
560
560
|
subscribe(listener: TAgentSessionChangeListener): () => void;
|
|
561
561
|
getEvents(): readonly TAgentEvent[];
|
|
562
562
|
getModelMessages(): ModelMessage[];
|