@modelprofile.com/flexharness 3.7.0 → 4.0.0

package/ts/classes.stores.ts

@@ -10,12 +10,17 @@ import type {
   IFlexHarnessStores,
   IFlexPermissionSnapshot,
   IFlexPermissionStore,
-  IFlexProjectionSnapshotV2,
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementStore,
+  IFlexProjectManagementTombstone,
+  IFlexProjectManagementWriteContext,
+  IFlexProjectionSnapshotV3,
   IFlexProjectionStore,
   IFlexScopeSnapshot,
   IFlexScopeStore,
   IFlexToolJobStoreProvider,
   TFlexProjectionSnapshot,
+  TFlexProjectManagementRecord,
 } from './interfaces.js';
 import {
   assertFlexPermissionSnapshot,
@@ -24,8 +29,17 @@ import {
   assertJsonSerializable,
   cloneSerializable,
 } from './utils.json.js';
-
-type TSnapshot = IFlexScopeSnapshot | TFlexProjectionSnapshot | IFlexPermissionSnapshot;
+import {
+  assertFlexProjectManagementRecord,
+  assertFlexProjectManagementSnapshot,
+  assertFlexProjectManagementTombstone,
+} from './utils.projectmanagement.js';
+
+type TSnapshot =
+  | IFlexScopeSnapshot
+  | TFlexProjectionSnapshot
+  | IFlexPermissionSnapshot
+  | TFlexProjectManagementRecord;
 type TSnapshotValidator<TSnapshotValue extends TSnapshot> = (
   value: unknown,
 ) => asserts value is TSnapshotValue;
@@ -42,6 +56,20 @@ function validateExpectedRevision(expectedRevision: number): void {
   }
 }
 
+function validateProjectManagementWriteContext(
+  writeContext: IFlexProjectManagementWriteContext,
+): void {
+  assertJsonSerializable(writeContext, '$writeContext');
+  assertRecord(writeContext, 'writeContext');
+  assertExactKeys(writeContext, ['actor', 'runId', 'agent', 'toolCallId'], 'writeContext');
+  if (writeContext.actor !== 'agent' && writeContext.actor !== 'application') {
+    throw new FlexHarnessValidationError('writeContext.actor must be agent or application.');
+  }
+  for (const key of ['runId', 'agent', 'toolCallId'] as const) {
+    if (writeContext[key] !== undefined) validateIdentifier(writeContext[key], `writeContext.${key}`);
+  }
+}
+
 function validateSnapshotSave<TSnapshotValue extends TSnapshot>(
   snapshot: TSnapshotValue,
   expectedRevision: number,
@@ -63,6 +91,25 @@ function providerKey(storageKey: string, sessionId: string): string {
   return JSON.stringify([storageKey, sessionId]);
 }
 
+function sameProjectManagementGeneration(
+  left: TFlexProjectManagementRecord,
+  right: TFlexProjectManagementRecord,
+): boolean {
+  return left.sessionGenerationId === right.sessionGenerationId
+    && left.sessionGenerationSequence === right.sessionGenerationSequence;
+}
+
+function canInitializeProjectManagementGeneration(
+  current: TFlexProjectManagementRecord,
+  next: TFlexProjectManagementRecord,
+  expectedRevision: number,
+): boolean {
+  return 'deletedAt' in current
+    && expectedRevision === 0
+    && next.sessionGenerationId !== current.sessionGenerationId
+    && next.sessionGenerationSequence > current.sessionGenerationSequence;
+}
+
 function assertProjectionSession(snapshot: TFlexProjectionSnapshot, sessionId: string): void {
   for (const message of snapshot.messages) {
     if (message.sessionId !== sessionId) {
@@ -365,7 +412,7 @@ class InMemoryProjectionStore implements IFlexProjectionStore {
   public async save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshotV2,
+    snapshot: IFlexProjectionSnapshotV3,
     expectedRevision: number,
   ): Promise<void> {
     const key = providerKey(storageKey, sessionId);
@@ -414,6 +461,81 @@ class InMemoryPermissionStore implements IFlexPermissionStore {
   }
 }
 
+export class InMemoryFlexProjectManagementStore implements IFlexProjectManagementStore {
+  private readonly snapshots = new Map<string, TFlexProjectManagementRecord>();
+
+  public async load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<TFlexProjectManagementRecord | undefined> {
+    const snapshot = this.snapshots.get(providerKey(storageKey, sessionId));
+    return snapshot ? cloneSerializable(snapshot) : undefined;
+  }
+
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectManagementSnapshot,
+    expectedRevision: number,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    validateProjectManagementWriteContext(writeContext);
+    const validated = validateSnapshotSave(
+      snapshot,
+      expectedRevision,
+      assertFlexProjectManagementSnapshot,
+    );
+    const current = this.snapshots.get(key);
+    const actualRevision = current?.revision ?? 0;
+    if (current && !sameProjectManagementGeneration(current, validated)) {
+      if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
+        throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+      }
+    } else if ((current && 'deletedAt' in current) || actualRevision !== expectedRevision) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+    this.snapshots.set(key, validated);
+  }
+
+  public async tombstoneSession(
+    storageKey: string,
+    sessionId: string,
+    tombstone: IFlexProjectManagementTombstone,
+    expectedRevision: number,
+  ): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const validated = validateSnapshotSave(
+      tombstone,
+      expectedRevision,
+      assertFlexProjectManagementTombstone,
+    );
+    const current = this.snapshots.get(key);
+    const actualRevision = current?.revision ?? 0;
+    if (current && sameProjectManagementGeneration(current, validated)) {
+      if ('deletedAt' in current) return;
+      if (actualRevision !== expectedRevision) {
+        throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+      }
+    } else if (current) {
+      if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
+        throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+      }
+    } else if (actualRevision !== expectedRevision) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+    this.snapshots.set(key, validated);
+  }
+
+  public async purgeNamespace(storageKey: string): Promise<void> {
+    validateIdentifier(storageKey, 'storageKey');
+    for (const key of this.snapshots.keys()) {
+      const [recordStorageKey] = JSON.parse(key) as [string, string];
+      if (recordStorageKey === storageKey) this.snapshots.delete(key);
+    }
+  }
+}
+
 class InMemoryAgentEventStore implements plugins.IAgentEventStoreV2 {
   public readonly eventSchemaVersion = 2 as const;
   private snapshot: plugins.IAgentEventSnapshotV2 | undefined;
@@ -563,9 +685,18 @@ export class InMemoryFlexHarnessStores implements IFlexHarnessStores {
   public readonly permissions: IFlexPermissionStore = new InMemoryPermissionStore();
   public readonly agentEvents: IFlexAgentEventStoreProvider = new InMemoryAgentEventStoreProvider();
   public readonly jobs: IFlexToolJobStoreProvider = new InMemoryToolJobStoreProvider();
+  public readonly projectManagement = new InMemoryFlexProjectManagementStore();
 }
 
-const jsonDomains = ['scopes', 'projections', 'permissions', 'events', 'archives', 'jobs'] as const;
+const jsonDomains = [
+  'scopes',
+  'projections',
+  'permissions',
+  'projectManagement',
+  'events',
+  'archives',
+  'jobs',
+] as const;
 type TJsonDomain = (typeof jsonDomains)[number];
 
 interface IDirectorySyncAttempt {
@@ -621,6 +752,11 @@ class JsonFileRoot {
     );
   }
 
+  public sessionNamespacePath(domain: TJsonDomain, storageKey: string): string {
+    validateIdentifier(storageKey, 'storageKey');
+    return plugins.path.join(this.directory, domain, this.digest(storageKey));
+  }
+
   public archivePath(storageKey: string, sessionId: string, archiveId: string): string {
     validateIdentifier(archiveId, 'archiveId');
     return plugins.path.join(
@@ -988,7 +1124,7 @@ class JsonProjectionStore implements IFlexProjectionStore {
   public async save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshotV2,
+    snapshot: IFlexProjectionSnapshotV3,
     expectedRevision: number,
   ): Promise<void> {
     const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexProjectionSnapshot);
@@ -1058,6 +1194,127 @@ class JsonPermissionStore implements IFlexPermissionStore {
   }
 }
 
+class JsonProjectManagementStore implements IFlexProjectManagementStore {
+  constructor(private readonly root: JsonFileRoot) {}
+
+  private inNamespaceQueue<T>(storageKey: string, operation: () => Promise<T>): Promise<T> {
+    return JsonFileRoot.inQueue(
+      `project-management:${this.root.sessionNamespacePath('projectManagement', storageKey)}`,
+      operation,
+    );
+  }
+
+  public async load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<TFlexProjectManagementRecord | undefined> {
+    const filePath = this.root.sessionPath('projectManagement', storageKey, sessionId);
+    return this.inNamespaceQueue(storageKey, () =>
+      JsonFileRoot.inQueue(filePath, async () => {
+        const snapshot = await this.root.read(filePath, (value) => {
+          assertFlexProjectManagementRecord(value);
+          return value;
+        });
+        return snapshot ? cloneSerializable(snapshot) : undefined;
+      })
+    );
+  }
+
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectManagementSnapshot,
+    expectedRevision: number,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<void> {
+    validateProjectManagementWriteContext(writeContext);
+    const validated = validateSnapshotSave(
+      snapshot,
+      expectedRevision,
+      assertFlexProjectManagementSnapshot,
+    );
+    const filePath = this.root.sessionPath('projectManagement', storageKey, sessionId);
+    await this.inNamespaceQueue(storageKey, () =>
+      JsonFileRoot.inQueue(filePath, async () => {
+        const current = await this.root.read(filePath, (value) => {
+          assertFlexProjectManagementRecord(value);
+          return value;
+        });
+        const actualRevision = current?.revision ?? 0;
+        if (current && !sameProjectManagementGeneration(current, validated)) {
+          if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
+            throw new FlexHarnessStoreConflictError(
+              providerKey(storageKey, sessionId),
+              expectedRevision,
+              actualRevision,
+            );
+          }
+        } else if ((current && 'deletedAt' in current) || actualRevision !== expectedRevision) {
+          throw new FlexHarnessStoreConflictError(
+            providerKey(storageKey, sessionId),
+            expectedRevision,
+            actualRevision,
+          );
+        }
+        await this.root.write(filePath, validated);
+      }),
+    );
+  }
+
+  public async tombstoneSession(
+    storageKey: string,
+    sessionId: string,
+    tombstone: IFlexProjectManagementTombstone,
+    expectedRevision: number,
+  ): Promise<void> {
+    const validated = validateSnapshotSave(
+      tombstone,
+      expectedRevision,
+      assertFlexProjectManagementTombstone,
+    );
+    const filePath = this.root.sessionPath('projectManagement', storageKey, sessionId);
+    await this.inNamespaceQueue(storageKey, () =>
+      JsonFileRoot.inQueue(filePath, async () => {
+        const current = await this.root.read(filePath, (value) => {
+          assertFlexProjectManagementRecord(value);
+          return value;
+        });
+        const actualRevision = current?.revision ?? 0;
+        if (current && sameProjectManagementGeneration(current, validated)) {
+          if ('deletedAt' in current) return;
+          if (actualRevision !== expectedRevision) {
+            throw new FlexHarnessStoreConflictError(
+              providerKey(storageKey, sessionId),
+              expectedRevision,
+              actualRevision,
+            );
+          }
+        } else if (current) {
+          if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
+            throw new FlexHarnessStoreConflictError(
+              providerKey(storageKey, sessionId),
+              expectedRevision,
+              actualRevision,
+            );
+          }
+        } else if (actualRevision !== expectedRevision) {
+          throw new FlexHarnessStoreConflictError(
+            providerKey(storageKey, sessionId),
+            expectedRevision,
+            actualRevision,
+          );
+        }
+        await this.root.write(filePath, validated);
+      }),
+    );
+  }
+
+  public async purgeNamespace(storageKey: string): Promise<void> {
+    const directory = this.root.sessionNamespacePath('projectManagement', storageKey);
+    await this.inNamespaceQueue(storageKey, () => this.root.deleteDirectory(directory));
+  }
+}
+
 async function clearJsonAgentEventSession(
   root: JsonFileRoot,
   storageKey: string,
@@ -1305,6 +1562,7 @@ export class JsonFileFlexHarnessStores implements IFlexHarnessStores {
   public readonly permissions: IFlexPermissionStore;
   public readonly agentEvents: IFlexAgentEventStoreProvider;
   public readonly jobs: IFlexToolJobStoreProvider;
+  public readonly projectManagement: IFlexProjectManagementStore;
   private readonly root: JsonFileRoot;
 
   constructor(options: IJsonFileFlexHarnessStoresOptions) {
@@ -1315,6 +1573,7 @@ export class JsonFileFlexHarnessStores implements IFlexHarnessStores {
     this.scopes = new JsonScopeStore(this.root);
     this.projections = new JsonProjectionStore(this.root);
     this.permissions = new JsonPermissionStore(this.root);
+    this.projectManagement = new JsonProjectManagementStore(this.root);
     this.agentEvents = new JsonAgentEventStoreProvider(this.root);
     this.jobs = new JsonToolJobStoreProvider(this.root);
   }

package/ts/index.ts

@@ -3,6 +3,12 @@ export * from './classes.stores.js';
 export * from './errors.js';
 export * from './interfaces.js';
 export { normalizeJsonValue } from './utils.json.js';
+export {
+  assertFlexProjectManagementSnapshot,
+  assertFlexProjectManagementRecord,
+  assertFlexProjectManagementTombstone,
+  createEmptyFlexProjectManagementSnapshot,
+} from './utils.projectmanagement.js';
 export {
   FLEX_SLASH_COMMAND_MAX_INPUT_BYTES,
   parseSlashCommand,