@modelprofile.com/flexharness-agent 6.0.0

package/ts_agent/smartagent.persistence.ts

@@ -0,0 +1,827 @@
+import * as plugins from './plugins.js';
+import type { TAgentEvent } from './smartagent.events.js';
+
+const SNAPSHOT_SCHEMA_VERSION = 2 as const;
+const ARCHIVE_SCHEMA_VERSION = 2 as const;
+
+interface IAgentEventSnapshotBase {
+  sessionId: string;
+  revision: number;
+  updatedAt: number;
+  events: TAgentEvent[];
+}
+
+/** Legacy schema-1 snapshot contract used by IAgentEventStore. */
+export interface IAgentEventSnapshot extends IAgentEventSnapshotBase {
+  schemaVersion: 1;
+}
+
+export interface IAgentEventSnapshotV2 extends IAgentEventSnapshotBase {
+  schemaVersion: 2;
+}
+
+export type TAgentEventSnapshot = IAgentEventSnapshot | IAgentEventSnapshotV2;
+
+interface IAgentEventArchiveBase {
+  sessionId: string;
+  archiveId: string;
+  createdAt: number;
+  events: TAgentEvent[];
+}
+
+/** Legacy schema-1 archive contract used by IAgentEventStore. */
+export interface IAgentEventArchive extends IAgentEventArchiveBase {
+  schemaVersion: 1;
+}
+
+export interface IAgentEventArchiveV2 extends IAgentEventArchiveBase {
+  schemaVersion: 2;
+}
+
+export type TAgentEventArchive = IAgentEventArchive | IAgentEventArchiveV2;
+
+/** Legacy custom-store contract. It must read and write schema 1 only. */
+export interface IAgentEventStore {
+  load(sessionId: string): Promise<IAgentEventSnapshot | undefined>;
+  save(
+    sessionId: string,
+    events: readonly TAgentEvent[],
+    expectedRevision: number,
+  ): Promise<number>;
+  archive?(archive: IAgentEventArchive): Promise<void>;
+  loadArchive?(sessionId: string, archiveId: string): Promise<IAgentEventArchive | undefined>;
+}
+
+/** Schema-2 capability required for persisted transactional generations. */
+export interface IAgentEventStoreV2 {
+  readonly eventSchemaVersion: 2;
+  load(sessionId: string): Promise<TAgentEventSnapshot | undefined>;
+  save(
+    sessionId: string,
+    events: readonly TAgentEvent[],
+    expectedRevision: number,
+  ): Promise<number>;
+  archive?(archive: IAgentEventArchiveV2): Promise<void>;
+  loadArchive?(sessionId: string, archiveId: string): Promise<TAgentEventArchive | undefined>;
+}
+
+export type TAgentEventStore = IAgentEventStore | IAgentEventStoreV2;
+
+export const isAgentEventStoreV2 = (
+  store: TAgentEventStore | undefined,
+): store is IAgentEventStoreV2 => !!store
+  && 'eventSchemaVersion' in store
+  && store.eventSchemaVersion === 2;
+
+type TUnknownRecord = Record<string, unknown>;
+
+const AGENT_EVENT_TYPES = new Set<string>([
+  'system-message',
+  'user-message',
+  'assistant-message',
+  'tool-call',
+  'tool-result',
+  'runtime-event',
+  'model-message',
+  'generation-begun',
+  'generation-execution-started',
+  'generation-execution-completed',
+  'generation-outcome',
+  'tool-execution-intent',
+  'tool-execution-reconciliation',
+  'context-compaction',
+] satisfies TAgentEvent['type'][]);
+
+const AGENT_CONVERSATION_EVENT_TYPES = new Set<string>([
+  'system-message',
+  'user-message',
+  'assistant-message',
+  'tool-call',
+  'tool-result',
+  'model-message',
+] satisfies TAgentEvent['type'][]);
+
+const hasOwn = (value: TUnknownRecord, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
+const validationError = (path: string, message: string): never => {
+  throw new Error(`${path} ${message}`);
+};
+
+const assertRecord: (
+  value: unknown,
+  path: string,
+) => asserts value is TUnknownRecord = (
+  value: unknown,
+  path: string,
+): void => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    validationError(path, 'must be an object.');
+  }
+};
+
+const assertNonEmptyString: (
+  value: unknown,
+  path: string,
+) => asserts value is string = (
+  value: unknown,
+  path: string,
+): void => {
+  if (typeof value !== 'string' || !value.trim()) {
+    validationError(path, 'must be a non-empty string.');
+  }
+};
+
+const assertOptionalString = (value: unknown, path: string): void => {
+  if (value !== undefined && typeof value !== 'string') {
+    validationError(path, 'must be a string when provided.');
+  }
+};
+
+const assertTimestamp = (value: unknown, path: string): void => {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    validationError(path, 'must be a non-negative finite number.');
+  }
+};
+
+const assertPositiveInteger: (
+  value: unknown,
+  path: string,
+) => asserts value is number = (value: unknown, path: string): void => {
+  if (!Number.isSafeInteger(value) || Number(value) <= 0) {
+    validationError(path, 'must be a positive safe integer.');
+  }
+};
+
+const assertStringArray: (
+  value: unknown,
+  path: string,
+) => asserts value is string[] = (value: unknown, path: string): void => {
+  if (!Array.isArray(value)) return validationError(path, 'must be an array.');
+  const values = new Set<string>();
+  for (const [index, entry] of value.entries()) {
+    assertNonEmptyString(entry, `${path}[${index}]`);
+    if (values.has(entry)) validationError(path, 'must not contain duplicate values.');
+    values.add(entry);
+  }
+};
+
+const assertProviderOptions = (value: unknown, path: string): void => {
+  if (value !== undefined) assertRecord(value, path);
+};
+
+const assertToolResultOutput = (value: unknown, path: string): void => {
+  assertRecord(value, path);
+  assertNonEmptyString(value.type, `${path}.type`);
+  assertProviderOptions(value.providerOptions, `${path}.providerOptions`);
+  if (value.type === 'text' || value.type === 'error-text') {
+    if (typeof value.value !== 'string') validationError(`${path}.value`, 'must be a string.');
+    return;
+  }
+  if (value.type === 'json' || value.type === 'error-json') {
+    if (!hasOwn(value, 'value')) validationError(`${path}.value`, 'is required.');
+    return;
+  }
+  if (value.type === 'execution-denied') {
+    assertOptionalString(value.reason, `${path}.reason`);
+    return;
+  }
+  if (value.type !== 'content') return validationError(`${path}.type`, 'is invalid.');
+  if (!Array.isArray(value.value)) {
+    return validationError(`${path}.value`, 'must be an array.');
+  }
+  for (const [index, entryValue] of value.value.entries()) {
+    const entryPath = `${path}.value[${index}]`;
+    assertRecord(entryValue, entryPath);
+    assertNonEmptyString(entryValue.type, `${entryPath}.type`);
+    assertProviderOptions(entryValue.providerOptions, `${entryPath}.providerOptions`);
+    if (entryValue.type === 'text') {
+      if (typeof entryValue.text !== 'string') validationError(`${entryPath}.text`, 'must be a string.');
+    } else if (
+      entryValue.type === 'media'
+      || entryValue.type === 'file-data'
+      || entryValue.type === 'image-data'
+    ) {
+      if (typeof entryValue.data !== 'string') validationError(`${entryPath}.data`, 'must be a string.');
+      if (typeof entryValue.mediaType !== 'string') {
+        validationError(`${entryPath}.mediaType`, 'must be a string.');
+      }
+      assertOptionalString(entryValue.filename, `${entryPath}.filename`);
+    } else if (entryValue.type === 'file-url' || entryValue.type === 'image-url') {
+      if (typeof entryValue.url !== 'string') validationError(`${entryPath}.url`, 'must be a string.');
+    } else if (entryValue.type === 'file-id' || entryValue.type === 'image-file-id') {
+      if (typeof entryValue.fileId !== 'string') {
+        assertRecord(entryValue.fileId, `${entryPath}.fileId`);
+        for (const [provider, fileId] of Object.entries(entryValue.fileId)) {
+          if (typeof fileId !== 'string') {
+            validationError(`${entryPath}.fileId.${provider}`, 'must be a string.');
+          }
+        }
+      }
+    } else if (entryValue.type !== 'custom') {
+      validationError(`${entryPath}.type`, 'is invalid.');
+    }
+  }
+};
+
+const assertMessageContentPart = (
+  value: unknown,
+  path: string,
+  role: 'user' | 'assistant' | 'tool',
+): void => {
+  assertRecord(value, path);
+  assertNonEmptyString(value.type, `${path}.type`);
+  assertProviderOptions(value.providerOptions, `${path}.providerOptions`);
+  if (value.type === 'text' || value.type === 'reasoning') {
+    if (value.type === 'reasoning' && role !== 'assistant') {
+      validationError(`${path}.type`, `is invalid for a ${role} message.`);
+    }
+    if (typeof value.text !== 'string') validationError(`${path}.text`, 'must be a string.');
+    return;
+  }
+  if (value.type === 'image') {
+    if (role !== 'user') validationError(`${path}.type`, `is invalid for a ${role} message.`);
+    if (!hasOwn(value, 'image')) validationError(`${path}.image`, 'is required.');
+    assertOptionalString(value.mediaType, `${path}.mediaType`);
+    return;
+  }
+  if (value.type === 'file') {
+    if (role === 'tool') validationError(`${path}.type`, 'is invalid for a tool message.');
+    if (!hasOwn(value, 'data')) validationError(`${path}.data`, 'is required.');
+    if (typeof value.mediaType !== 'string') validationError(`${path}.mediaType`, 'must be a string.');
+    assertOptionalString(value.filename, `${path}.filename`);
+    return;
+  }
+  if (value.type === 'tool-call') {
+    if (role !== 'assistant') validationError(`${path}.type`, `is invalid for a ${role} message.`);
+    assertNonEmptyString(value.toolCallId, `${path}.toolCallId`);
+    assertNonEmptyString(value.toolName, `${path}.toolName`);
+    if (!hasOwn(value, 'input')) validationError(`${path}.input`, 'is required.');
+    if (value.providerExecuted !== undefined && typeof value.providerExecuted !== 'boolean') {
+      validationError(`${path}.providerExecuted`, 'must be a boolean when provided.');
+    }
+    return;
+  }
+  if (value.type === 'tool-result') {
+    if (role === 'user') validationError(`${path}.type`, 'is invalid for a user message.');
+    assertNonEmptyString(value.toolCallId, `${path}.toolCallId`);
+    assertNonEmptyString(value.toolName, `${path}.toolName`);
+    if (!hasOwn(value, 'output')) validationError(`${path}.output`, 'is required.');
+    assertToolResultOutput(value.output, `${path}.output`);
+    return;
+  }
+  if (value.type === 'tool-approval-request') {
+    if (role !== 'assistant') validationError(`${path}.type`, `is invalid for a ${role} message.`);
+    assertNonEmptyString(value.approvalId, `${path}.approvalId`);
+    assertNonEmptyString(value.toolCallId, `${path}.toolCallId`);
+    return;
+  }
+  if (value.type === 'tool-approval-response') {
+    if (role !== 'tool') validationError(`${path}.type`, `is invalid for a ${role} message.`);
+    assertNonEmptyString(value.approvalId, `${path}.approvalId`);
+    if (typeof value.approved !== 'boolean') validationError(`${path}.approved`, 'must be a boolean.');
+    assertOptionalString(value.reason, `${path}.reason`);
+    if (value.providerExecuted !== undefined && typeof value.providerExecuted !== 'boolean') {
+      validationError(`${path}.providerExecuted`, 'must be a boolean when provided.');
+    }
+    return;
+  }
+  validationError(`${path}.type`, `is invalid for a ${role} message.`);
+};
+
+const assertMessageContent = (
+  value: unknown,
+  path: string,
+  role: 'system' | 'user' | 'assistant' | 'tool',
+): void => {
+  if (role === 'system') {
+    if (typeof value !== 'string') validationError(path, 'must be a string.');
+    return;
+  }
+  if (typeof value === 'string' && role !== 'tool') return;
+  if (!Array.isArray(value)) {
+    return validationError(path, 'must be a string or content-part array.');
+  }
+  for (const [index, part] of value.entries()) {
+    assertMessageContentPart(part, `${path}[${index}]`, role);
+  }
+};
+
+const assertModelMessage = (value: unknown, path: string): void => {
+  assertRecord(value, path);
+  const role = value.role;
+  if (
+    role !== 'system'
+    && role !== 'user'
+    && role !== 'assistant'
+    && role !== 'tool'
+  ) return validationError(`${path}.role`, 'is invalid.');
+  if (!hasOwn(value, 'content')) validationError(`${path}.content`, 'is required.');
+  assertMessageContent(value.content, `${path}.content`, role);
+  assertProviderOptions(value.providerOptions, `${path}.providerOptions`);
+};
+
+const assertRequiredGenerationId = (event: TUnknownRecord, path: string): void => {
+  assertNonEmptyString(event.generationId, `${path}.generationId`);
+};
+
+const assertArchivedTransactions = (value: unknown, path: string): void => {
+  if (!Array.isArray(value)) return validationError(path, 'must be an array.');
+  const generationIds = new Set<string>();
+  for (const [index, entryValue] of value.entries()) {
+    const entryPath = `${path}[${index}]`;
+    assertRecord(entryValue, entryPath);
+    assertNonEmptyString(entryValue.generationId, `${entryPath}.generationId`);
+    assertNonEmptyString(entryValue.claimTokenDigest, `${entryPath}.claimTokenDigest`);
+    if (generationIds.has(entryValue.generationId)) {
+      validationError(path, 'must not contain duplicate generationId values.');
+    }
+    generationIds.add(entryValue.generationId);
+    if (
+      entryValue.outcome !== 'accepted'
+      && entryValue.outcome !== 'rejected'
+      && entryValue.outcome !== 'interrupted'
+    ) validationError(`${entryPath}.outcome`, 'is invalid.');
+  }
+};
+
+const validateAgentEvents = (
+  value: unknown,
+  path: string,
+  conversationOnly = false,
+): TAgentEvent[] => {
+  if (!Array.isArray(value)) return validationError(path, 'must be an array.');
+  const eventIds = new Set<string>();
+  let priorSequence = 0;
+  for (const [index, eventValue] of value.entries()) {
+    const eventPath = `${path}[${index}]`;
+    assertRecord(eventValue, eventPath);
+    assertNonEmptyString(eventValue.id, `${eventPath}.id`);
+    if (eventIds.has(eventValue.id)) validationError(path, 'must not contain duplicate event IDs.');
+    eventIds.add(eventValue.id);
+    assertTimestamp(eventValue.timestamp, `${eventPath}.timestamp`);
+    if (eventValue.sequence !== undefined) {
+      assertPositiveInteger(eventValue.sequence, `${eventPath}.sequence`);
+      if (eventValue.sequence <= priorSequence) {
+        validationError(`${eventPath}.sequence`, 'must be strictly monotonic.');
+      }
+      priorSequence = eventValue.sequence;
+    }
+    if (eventValue.parentIds !== undefined) {
+      assertStringArray(eventValue.parentIds, `${eventPath}.parentIds`);
+    }
+    for (const field of ['causationId', 'generationId', 'inferenceId'] as const) {
+      if (eventValue[field] !== undefined) {
+        assertNonEmptyString(eventValue[field], `${eventPath}.${field}`);
+      }
+    }
+    assertNonEmptyString(eventValue.type, `${eventPath}.type`);
+    if (!AGENT_EVENT_TYPES.has(eventValue.type)) validationError(`${eventPath}.type`, 'is invalid.');
+    if (conversationOnly && !AGENT_CONVERSATION_EVENT_TYPES.has(eventValue.type)) {
+      validationError(`${eventPath}.type`, 'must be a conversation event.');
+    }
+    switch (eventValue.type) {
+      case 'system-message':
+        if (!hasOwn(eventValue, 'content')) validationError(`${eventPath}.content`, 'is required.');
+        assertMessageContent(eventValue.content, `${eventPath}.content`, 'system');
+        assertProviderOptions(eventValue.providerOptions, `${eventPath}.providerOptions`);
+        break;
+      case 'user-message':
+      case 'assistant-message':
+        if (!hasOwn(eventValue, 'content')) validationError(`${eventPath}.content`, 'is required.');
+        assertMessageContent(eventValue.content, `${eventPath}.content`, eventValue.type === 'user-message'
+          ? 'user'
+          : 'assistant');
+        assertProviderOptions(eventValue.providerOptions, `${eventPath}.providerOptions`);
+        break;
+      case 'tool-call':
+        assertNonEmptyString(eventValue.toolCallId, `${eventPath}.toolCallId`);
+        assertNonEmptyString(eventValue.toolName, `${eventPath}.toolName`);
+        if (!hasOwn(eventValue, 'input')) validationError(`${eventPath}.input`, 'is required.');
+        if (eventValue.providerExecuted !== undefined && typeof eventValue.providerExecuted !== 'boolean') {
+          validationError(`${eventPath}.providerExecuted`, 'must be a boolean when provided.');
+        }
+        assertProviderOptions(eventValue.providerOptions, `${eventPath}.providerOptions`);
+        break;
+      case 'tool-result':
+        assertNonEmptyString(eventValue.toolCallId, `${eventPath}.toolCallId`);
+        assertNonEmptyString(eventValue.toolName, `${eventPath}.toolName`);
+        if (eventValue.executionIntentId !== undefined) {
+          assertNonEmptyString(eventValue.executionIntentId, `${eventPath}.executionIntentId`);
+        }
+        assertOptionalString(eventValue.error, `${eventPath}.error`);
+        if (
+          eventValue.responseMessageCommitted !== undefined
+          && typeof eventValue.responseMessageCommitted !== 'boolean'
+        ) {
+          validationError(`${eventPath}.responseMessageCommitted`, 'must be a boolean when provided.');
+        }
+        if (eventValue.modelOutput !== undefined) {
+          assertToolResultOutput(eventValue.modelOutput, `${eventPath}.modelOutput`);
+        }
+        assertProviderOptions(eventValue.providerOptions, `${eventPath}.providerOptions`);
+        assertProviderOptions(eventValue.messageProviderOptions, `${eventPath}.messageProviderOptions`);
+        break;
+      case 'runtime-event':
+        assertRecord(eventValue.event, `${eventPath}.event`);
+        assertNonEmptyString(eventValue.event.type, `${eventPath}.event.type`);
+        if (eventValue.modelVisible !== undefined && typeof eventValue.modelVisible !== 'boolean') {
+          validationError(`${eventPath}.modelVisible`, 'must be a boolean when provided.');
+        }
+        break;
+      case 'model-message':
+        assertModelMessage(eventValue.message, `${eventPath}.message`);
+        break;
+      case 'generation-begun':
+        assertRequiredGenerationId(eventValue, eventPath);
+        assertNonEmptyString(eventValue.claimTokenDigest, `${eventPath}.claimTokenDigest`);
+        break;
+      case 'generation-execution-started':
+      case 'generation-execution-completed':
+        assertRequiredGenerationId(eventValue, eventPath);
+        break;
+      case 'generation-outcome':
+        assertRequiredGenerationId(eventValue, eventPath);
+        if (
+          eventValue.outcome !== 'accepted'
+          && eventValue.outcome !== 'rejected'
+          && eventValue.outcome !== 'interrupted'
+        ) validationError(`${eventPath}.outcome`, 'is invalid.');
+        assertOptionalString(eventValue.reason, `${eventPath}.reason`);
+        break;
+      case 'tool-execution-intent':
+        assertRequiredGenerationId(eventValue, eventPath);
+        assertNonEmptyString(eventValue.toolCallId, `${eventPath}.toolCallId`);
+        assertNonEmptyString(eventValue.toolName, `${eventPath}.toolName`);
+        if (!hasOwn(eventValue, 'input')) validationError(`${eventPath}.input`, 'is required.');
+        break;
+      case 'tool-execution-reconciliation':
+        assertRequiredGenerationId(eventValue, eventPath);
+        assertNonEmptyString(eventValue.intentId, `${eventPath}.intentId`);
+        assertNonEmptyString(eventValue.toolCallId, `${eventPath}.toolCallId`);
+        assertNonEmptyString(eventValue.toolName, `${eventPath}.toolName`);
+        if (
+          eventValue.resolution !== 'executed'
+          && eventValue.resolution !== 'not-executed'
+          && eventValue.resolution !== 'abandoned-unknown'
+        ) validationError(`${eventPath}.resolution`, 'is invalid.');
+        assertOptionalString(eventValue.error, `${eventPath}.error`);
+        if (eventValue.modelOutput !== undefined) {
+          assertToolResultOutput(eventValue.modelOutput, `${eventPath}.modelOutput`);
+        }
+        break;
+      case 'context-compaction':
+        assertStringArray(eventValue.coveredEventIds, `${eventPath}.coveredEventIds`);
+        validateAgentEvents(eventValue.replacementEvents, `${eventPath}.replacementEvents`, true);
+        if (eventValue.archivedTransactions !== undefined) {
+          assertArchivedTransactions(
+            eventValue.archivedTransactions,
+            `${eventPath}.archivedTransactions`,
+          );
+        }
+        break;
+    }
+  }
+  return value as TAgentEvent[];
+};
+
+/** Validates and returns a canonical schema-2 Agent event snapshot. */
+export const validateAgentEventSnapshotV2 = (
+  value: unknown,
+  expectedSessionId?: string,
+): IAgentEventSnapshotV2 => {
+  assertRecord(value, 'Agent event snapshot');
+  if (value.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+    validationError('Agent event snapshot schemaVersion', 'must be 2.');
+  }
+  assertNonEmptyString(value.sessionId, 'Agent event snapshot sessionId');
+  if (expectedSessionId !== undefined && value.sessionId !== expectedSessionId) {
+    validationError('Agent event snapshot sessionId', `must equal "${expectedSessionId}".`);
+  }
+  assertPositiveInteger(value.revision, 'Agent event snapshot revision');
+  assertTimestamp(value.updatedAt, 'Agent event snapshot updatedAt');
+  validateAgentEvents(value.events, 'Agent event snapshot events');
+  return value as unknown as IAgentEventSnapshotV2;
+};
+
+/** Validates and returns a canonical schema-2 Agent event archive. */
+export const validateAgentEventArchiveV2 = (
+  value: unknown,
+  expectedSessionId?: string,
+  expectedArchiveId?: string,
+): IAgentEventArchiveV2 => {
+  assertRecord(value, 'Agent event archive');
+  if (value.schemaVersion !== ARCHIVE_SCHEMA_VERSION) {
+    validationError('Agent event archive schemaVersion', 'must be 2.');
+  }
+  assertNonEmptyString(value.sessionId, 'Agent event archive sessionId');
+  if (expectedSessionId !== undefined && value.sessionId !== expectedSessionId) {
+    validationError('Agent event archive sessionId', `must equal "${expectedSessionId}".`);
+  }
+  assertNonEmptyString(value.archiveId, 'Agent event archive archiveId');
+  if (expectedArchiveId !== undefined && value.archiveId !== expectedArchiveId) {
+    validationError('Agent event archive archiveId', `must equal "${expectedArchiveId}".`);
+  }
+  assertTimestamp(value.createdAt, 'Agent event archive createdAt');
+  validateAgentEvents(value.events, 'Agent event archive events');
+  return value as unknown as IAgentEventArchiveV2;
+};
+
+export class AgentEventStoreConflictError extends Error {
+  public readonly sessionId: string;
+  public readonly expectedRevision: number;
+  public readonly actualRevision: number;
+
+  constructor(sessionId: string, expectedRevision: number, actualRevision: number) {
+    super(
+      `Agent event store conflict for session "${sessionId}": expected revision ${expectedRevision}, found ${actualRevision}.`,
+    );
+    this.name = 'AgentEventStoreConflictError';
+    this.sessionId = sessionId;
+    this.expectedRevision = expectedRevision;
+    this.actualRevision = actualRevision;
+  }
+}
+
+const clone = <TValue>(value: TValue): TValue => structuredClone(value);
+
+const createSnapshot = (
+  sessionId: string,
+  revision: number,
+  events: readonly TAgentEvent[],
+): IAgentEventSnapshotV2 => ({
+  schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+  sessionId,
+  revision,
+  updatedAt: Date.now(),
+  events: clone([...events]),
+});
+
+export class InMemoryAgentEventStore implements IAgentEventStoreV2 {
+  public readonly eventSchemaVersion = 2 as const;
+  private readonly snapshots = new Map<string, TAgentEventSnapshot>();
+  private readonly archives = new Map<string, TAgentEventArchive>();
+
+  public async load(sessionId: string): Promise<TAgentEventSnapshot | undefined> {
+    const snapshot = this.snapshots.get(sessionId);
+    return snapshot ? clone(snapshot) : undefined;
+  }
+
+  public async save(
+    sessionId: string,
+    events: readonly TAgentEvent[],
+    expectedRevision: number,
+  ): Promise<number> {
+    const actualRevision = this.snapshots.get(sessionId)?.revision ?? 0;
+    if (actualRevision !== expectedRevision) {
+      throw new AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
+    }
+    const revision = expectedRevision + 1;
+    this.snapshots.set(sessionId, createSnapshot(sessionId, revision, events));
+    return revision;
+  }
+
+  public async archive(archive: IAgentEventArchiveV2): Promise<void> {
+    const nextArchive = clone(archive);
+    const key = `${archive.sessionId}\n${archive.archiveId}`;
+    const existing = this.archives.get(key);
+    if (existing) {
+      const existingIds = existing.events.map((event) => event.id).join('\n');
+      const nextIds = nextArchive.events.map((event) => event.id).join('\n');
+      if (existingIds !== nextIds) {
+        throw new Error(`Archive "${archive.archiveId}" already exists with different events.`);
+      }
+      return;
+    }
+    this.archives.set(key, nextArchive);
+  }
+
+  public async loadArchive(
+    sessionId: string,
+    archiveId: string,
+  ): Promise<TAgentEventArchive | undefined> {
+    const archive = this.archives.get(`${sessionId}\n${archiveId}`);
+    return archive ? clone(archive) : undefined;
+  }
+}
+
+export interface IFileAgentEventStoreOptions {
+  rootDir: string;
+  /** Maximum time spent waiting for another writer. Default: 10 seconds. */
+  lockTimeoutMs?: number;
+}
+
+const assertSessionId = (sessionId: string): void => {
+  if (!sessionId.trim()) throw new Error('Agent event store sessionId must not be empty.');
+};
+
+const decodeSnapshot = (value: unknown, sessionId: string): TAgentEventSnapshot => {
+  const snapshot = value as Partial<TAgentEventSnapshot>;
+  if (snapshot?.schemaVersion === SNAPSHOT_SCHEMA_VERSION) {
+    try {
+      return validateAgentEventSnapshotV2(value, sessionId);
+    } catch {
+      throw new Error(`Invalid agent event snapshot for session "${sessionId}".`);
+    }
+  }
+  if (
+    !snapshot
+    || snapshot.schemaVersion !== 1
+    || snapshot.sessionId !== sessionId
+    || !Number.isSafeInteger(snapshot.revision)
+    || (snapshot.revision ?? -1) < 1
+    || !Array.isArray(snapshot.events)
+  ) {
+    throw new Error(`Invalid agent event snapshot for session "${sessionId}".`);
+  }
+  return snapshot as TAgentEventSnapshot;
+};
+
+const decodeArchive = (
+  value: unknown,
+  sessionId: string,
+  archiveId: string,
+): TAgentEventArchive => {
+  const archive = value as Partial<TAgentEventArchive>;
+  if (archive?.schemaVersion === ARCHIVE_SCHEMA_VERSION) {
+    try {
+      return validateAgentEventArchiveV2(value, sessionId, archiveId);
+    } catch {
+      throw new Error(`Invalid agent event archive "${archiveId}" for session "${sessionId}".`);
+    }
+  }
+  if (
+    !archive
+    || archive.schemaVersion !== 1
+    || archive.sessionId !== sessionId
+    || archive.archiveId !== archiveId
+    || !Array.isArray(archive.events)
+  ) {
+    throw new Error(`Invalid agent event archive "${archiveId}" for session "${sessionId}".`);
+  }
+  return archive as TAgentEventArchive;
+};
+
+const sleep = async (milliseconds: number): Promise<void> => {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+};
+
+export class FileAgentEventStore implements IAgentEventStoreV2 {
+  public readonly eventSchemaVersion = 2 as const;
+  private readonly rootDir: string;
+  private readonly lockTimeoutMs: number;
+
+  constructor(options: IFileAgentEventStoreOptions) {
+    if (!options.rootDir.trim()) throw new Error('FileAgentEventStore rootDir must not be empty.');
+    this.rootDir = plugins.path.resolve(options.rootDir);
+    this.lockTimeoutMs = options.lockTimeoutMs ?? 10_000;
+    if (!Number.isSafeInteger(this.lockTimeoutMs) || this.lockTimeoutMs <= 0) {
+      throw new Error('lockTimeoutMs must be a positive integer.');
+    }
+  }
+
+  private sessionKey(sessionId: string): string {
+    assertSessionId(sessionId);
+    return plugins.crypto.createHash('sha256').update(sessionId).digest('hex');
+  }
+
+  private snapshotPath(sessionId: string): string {
+    return plugins.path.join(this.rootDir, 'sessions', `${this.sessionKey(sessionId)}.bin`);
+  }
+
+  private archivePath(sessionId: string, archiveId: string): string {
+    if (!archiveId.trim()) throw new Error('Agent event archiveId must not be empty.');
+    const archiveKey = plugins.crypto.createHash('sha256').update(archiveId).digest('hex');
+    return plugins.path.join(this.rootDir, 'archives', this.sessionKey(sessionId), `${archiveKey}.bin`);
+  }
+
+  private async readValue(filePath: string): Promise<unknown | undefined> {
+    try {
+      return plugins.v8.deserialize(await plugins.fs.readFile(filePath));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw error;
+    }
+  }
+
+  private async syncDirectory(directoryPath: string): Promise<void> {
+    const handle = await plugins.fs.open(directoryPath, 'r');
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  }
+
+  private async writeAtomic(filePath: string, value: unknown): Promise<void> {
+    const directoryPath = plugins.path.dirname(filePath);
+    await plugins.fs.mkdir(directoryPath, { recursive: true });
+    const temporaryPath = `${filePath}.${process.pid}.${plugins.crypto.randomUUID()}.tmp`;
+    let handle: Awaited<ReturnType<typeof plugins.fs.open>> | undefined;
+    try {
+      handle = await plugins.fs.open(temporaryPath, 'wx');
+      await handle.writeFile(plugins.v8.serialize(value));
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await plugins.fs.rename(temporaryPath, filePath);
+      await this.syncDirectory(directoryPath);
+    } finally {
+      if (handle) await handle.close().catch(() => undefined);
+      await plugins.fs.rm(temporaryPath, { force: true });
+    }
+  }
+
+  private async withSessionLock<TValue>(
+    sessionId: string,
+    operation: () => Promise<TValue>,
+  ): Promise<TValue> {
+    const lockPath = plugins.path.join(this.rootDir, 'locks', `${this.sessionKey(sessionId)}.lock`);
+    const ownerPath = plugins.path.join(lockPath, 'owner');
+    const ownerToken = plugins.crypto.randomUUID();
+    const ownerRecord = JSON.stringify({ token: ownerToken });
+    await plugins.fs.mkdir(plugins.path.dirname(lockPath), { recursive: true });
+    const startedAt = Date.now();
+    while (true) {
+      try {
+        await plugins.fs.mkdir(lockPath);
+        try {
+          await plugins.fs.writeFile(ownerPath, ownerRecord, 'utf8');
+        } catch (error) {
+          await plugins.fs.rm(lockPath, { recursive: true, force: true });
+          throw error;
+        }
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        if (Date.now() - startedAt >= this.lockTimeoutMs) {
+          throw new Error(
+            `Timed out waiting for the event-store lock for session "${sessionId}" at "${lockPath}".`,
+          );
+        }
+        await sleep(20);
+      }
+    }
+    try {
+      return await operation();
+    } finally {
+      let stillOwner = false;
+      try {
+        const owner = JSON.parse(await plugins.fs.readFile(ownerPath, 'utf8')) as { token?: unknown };
+        stillOwner = owner.token === ownerToken;
+      } catch {}
+      if (stillOwner) await plugins.fs.rm(lockPath, { recursive: true, force: true });
+    }
+  }
+
+  public async load(sessionId: string): Promise<TAgentEventSnapshot | undefined> {
+    const value = await this.readValue(this.snapshotPath(sessionId));
+    return value === undefined ? undefined : decodeSnapshot(value, sessionId);
+  }
+
+  public async save(
+    sessionId: string,
+    events: readonly TAgentEvent[],
+    expectedRevision: number,
+  ): Promise<number> {
+    return this.withSessionLock(sessionId, async () => {
+      const filePath = this.snapshotPath(sessionId);
+      const currentValue = await this.readValue(filePath);
+      const actualRevision = currentValue === undefined
+        ? 0
+        : decodeSnapshot(currentValue, sessionId).revision;
+      if (actualRevision !== expectedRevision) {
+        throw new AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
+      }
+      const revision = expectedRevision + 1;
+      await this.writeAtomic(filePath, createSnapshot(sessionId, revision, events));
+      return revision;
+    });
+  }
+
+  public async archive(archive: IAgentEventArchiveV2): Promise<void> {
+    const nextArchive = clone(archive);
+    await this.withSessionLock(archive.sessionId, async () => {
+      const filePath = this.archivePath(archive.sessionId, archive.archiveId);
+      const currentValue = await this.readValue(filePath);
+      if (currentValue !== undefined) {
+        const current = decodeArchive(currentValue, archive.sessionId, archive.archiveId);
+        const currentIds = current.events.map((event) => event.id).join('\n');
+        const nextIds = nextArchive.events.map((event) => event.id).join('\n');
+        if (currentIds !== nextIds) {
+          throw new Error(`Archive "${archive.archiveId}" already exists with different events.`);
+        }
+        return;
+      }
+      await this.writeAtomic(filePath, nextArchive);
+    });
+  }
+
+  public async loadArchive(
+    sessionId: string,
+    archiveId: string,
+  ): Promise<TAgentEventArchive | undefined> {
+    const value = await this.readValue(this.archivePath(sessionId, archiveId));
+    return value === undefined ? undefined : decodeArchive(value, sessionId, archiveId);
+  }
+}