@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/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 `IAgentEventStoreV2` store with `eventSchemaVersion: 2`; without a store, transactions are process-local.
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 { IAgentEventStoreV2 } from '@modelprofile.com/flexharness-agent';
322
+ import type { IAgentEventStore } from '@modelprofile.com/flexharness-agent';
323
323
 
324
- export function openStoredSession(eventStore: IAgentEventStoreV2, sessionId: string) {
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. Its `save(sessionId, events, expectedRevision)` must atomically compare the revision and return the new revision, or reject a conflict. Preserve the schema and supported values in canonical events; the package exports schema validators and `AgentEventStoreConflictError` for adapter implementations. Keep one active owner per session; compare-and-swap detects conflicting writes rather than merging competing 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
- Commits queued before a save starts share one durable snapshot containing them all. An in-flight snapshot is immutable, and every caller and change notification still waits for the save containing its event. The adapter's revision advances per durable snapshot, not necessarily per event.
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
- IAgentEventArchiveV2,
73
- TAgentEventArchive,
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, TAgentEventSnapshot | undefined>();
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
- private pendingPersistence?: { snapshot: TAgentEvent[]; task: Promise<void> };
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
- let snapshot = await options.eventStore.load(options.sessionId);
390
- const v2Store = isAgentEventStoreV2(options.eventStore);
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
- const snapshot = structuredClone(this.events);
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
- if (this.pendingPersistence === pending) this.pendingPersistence = undefined;
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
- pending.snapshot,
570
+ change,
602
571
  this.persistenceRevision,
603
572
  );
604
573
  });
605
- // One durable snapshot covers every commit queued before this write begins. In-flight snapshots
606
- // stay immutable, and callers still wait for the write that contains their event.
607
- pending = { snapshot, task: operation };
608
- this.pendingPersistence = pending;
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
- if (this.options.eventStore) structuredClone(events);
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<TAgentEventArchive | undefined> {
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<TAgentEventArchive | undefined> {
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 isAgentEventStoreV2(eventStore)
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 archiveBase = {
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
- if (isAgentEventStoreV2(eventStore)) {
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
- isAgentEventStoreV2,
41
- validateAgentEventArchiveV2,
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
- IAgentEventArchiveV2,
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, createSnapshot,
5
- validateAgentEventArchiveV2, validateAgentEventSnapshotV2,
6
- type IAgentEventArchiveV2, type IAgentEventStoreV2,
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): TAgentEventSnapshot => {
24
- const snapshot = value as Partial<TAgentEventSnapshot>;
25
- if (snapshot?.schemaVersion === SNAPSHOT_SCHEMA_VERSION) {
26
- try {
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
- ): TAgentEventArchive => {
50
- const archive = value as Partial<TAgentEventArchive>;
51
- if (archive?.schemaVersion === ARCHIVE_SCHEMA_VERSION) {
52
- try {
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
- export class FileAgentEventStore implements IAgentEventStoreV2 {
75
- public readonly eventSchemaVersion = 2 as const;
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<TAgentEventSnapshot | undefined> {
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
- events: readonly TAgentEvent[],
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 actualRevision = currentValue === undefined
196
- ? 0
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 revision = expectedRevision + 1;
202
- await this.writeAtomic(filePath, createSnapshot(sessionId, revision, events));
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: IAgentEventArchiveV2): Promise<void> {
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<TAgentEventArchive | undefined> {
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
  }
@@ -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 `IAgentEventStoreV2` store with `eventSchemaVersion: 2`; without a store, transactions are process-local.
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 { IAgentEventStoreV2 } from '@modelprofile.com/flexharness-agent';
322
+ import type { IAgentEventStore } from '@modelprofile.com/flexharness-agent';
323
323
 
324
- export function openStoredSession(eventStore: IAgentEventStoreV2, sessionId: string) {
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. Its `save(sessionId, events, expectedRevision)` must atomically compare the revision and return the new revision, or reject a conflict. Preserve the schema and supported values in canonical events; the package exports schema validators and `AgentEventStoreConflictError` for adapter implementations. Keep one active owner per session; compare-and-swap detects conflicting writes rather than merging competing 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
- Commits queued before a save starts share one durable snapshot containing them all. An in-flight snapshot is immutable, and every caller and change notification still waits for the save containing its event. The adapter's revision advances per durable snapshot, not necessarily per event.
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 { TAgentEventArchive, TAgentEventStore } from './smartagent.persistence.js';
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. Transactional persistence requires IAgentEventStoreV2. */
225
- eventStore?: TAgentEventStore;
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 V2 execution authority first; legacy/process-local calls do not.
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<TAgentEventArchive | undefined>;
559
+ archiveCompactedEvents(compactionEventId?: string): Promise<IAgentEventArchive | undefined>;
560
560
  subscribe(listener: TAgentSessionChangeListener): () => void;
561
561
  getEvents(): readonly TAgentEvent[];
562
562
  getModelMessages(): ModelMessage[];