@modelprofile.com/flexharness 3.8.0 → 4.0.1

package/ts/classes.stores.ts

@@ -10,12 +10,17 @@ import type {
   IFlexHarnessStores,
   IFlexPermissionSnapshot,
   IFlexPermissionStore,
+  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) {
@@ -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(
@@ -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,

package/ts/interfaces.ts

@@ -135,6 +135,8 @@ export interface IFlexSessionActivity {
 export interface IFlexSession {
   scopeId: string;
   sessionId: string;
+  sessionGenerationId?: string;
+  sessionGenerationSequence?: number;
   title?: string;
   createdAt: string;
   updatedAt: string;
@@ -428,6 +430,8 @@ export interface IFlexResourceToolProviderResolver<TScope> {
 
 export interface IFlexSessionTombstone {
   sessionId: string;
+  sessionGenerationId?: string;
+  sessionGenerationSequence?: number;
   deletedAt: string;
   rootSessionId?: string;
   depth?: number;
@@ -564,6 +568,118 @@ export interface IFlexPermissionSnapshot {
   rememberedPermissionKeys: string[];
 }
 
+export const FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION = 1 as const;
+export const FLEX_SESSION_GENERATION_ID_MAX_BYTES = 128;
+
+export const FLEX_PROJECT_MANAGEMENT_LIMITS = Object.freeze({
+  maxGoalBytes: 8 * 1024,
+  maxScratchpadBytes: 128 * 1024,
+  maxTaskContentBytes: 8 * 1024,
+  maxTaskIdBytes: 512,
+  maxTasks: 512,
+  maxTitleBytes: 2048,
+  maxSnapshotBytes: 1024 * 1024,
+});
+
+export type TFlexProjectTaskStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+export type TFlexProjectTaskPriority = 'high' | 'medium' | 'low';
+
+export interface IFlexProjectTask {
+  id: string;
+  content: string;
+  status: TFlexProjectTaskStatus;
+  priority: TFlexProjectTaskPriority;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface IFlexProjectManagementSnapshot {
+  schemaVersion: 1;
+  revision: number;
+  sessionGenerationId: string;
+  sessionGenerationSequence: number;
+  goal?: string;
+  scratchpad: string;
+  tasks: IFlexProjectTask[];
+}
+
+export interface IFlexProjectManagementTombstone {
+  schemaVersion: 1;
+  revision: number;
+  sessionGenerationId: string;
+  sessionGenerationSequence: number;
+  deletedAt: string;
+}
+
+export type TFlexProjectManagementRecord =
+  | IFlexProjectManagementSnapshot
+  | IFlexProjectManagementTombstone;
+
+export type TFlexProjectManagementWriteActor = 'agent' | 'application';
+
+export interface IFlexProjectManagementWriteContext {
+  actor: TFlexProjectManagementWriteActor;
+  runId?: string;
+  agent?: string;
+  toolCallId?: string;
+}
+
+export interface IFlexProjectManagementStore {
+  load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<TFlexProjectManagementRecord | undefined>;
+  save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectManagementSnapshot,
+    expectedRevision: number,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<void>;
+  tombstoneSession(
+    storageKey: string,
+    sessionId: string,
+    tombstone: IFlexProjectManagementTombstone,
+    expectedRevision: number,
+  ): Promise<void>;
+  purgeNamespace(storageKey: string): Promise<void>;
+}
+
+export interface IFlexCreateProjectTaskInput {
+  id: string;
+  content: string;
+  status?: TFlexProjectTaskStatus;
+  priority?: TFlexProjectTaskPriority;
+}
+
+export interface IFlexUpdateProjectTaskInput {
+  id: string;
+  content?: string;
+  status?: TFlexProjectTaskStatus;
+  priority?: TFlexProjectTaskPriority;
+}
+
+export interface IFlexProjectStateResult {
+  revision: number;
+  state: IFlexProjectManagementSnapshot;
+}
+
+export interface IFlexProjectTaskResult extends IFlexProjectStateResult {
+  task: IFlexProjectTask;
+}
+
+export interface IFlexProjectTasksResult extends IFlexProjectStateResult {
+  tasks: IFlexProjectTask[];
+}
+
+export interface IFlexProjectGoalResult extends IFlexProjectStateResult {
+  goal: string | null;
+}
+
+export interface IFlexProjectScratchpadResult extends IFlexProjectStateResult {
+  scratchpad: string;
+}
+
 export interface IFlexScopeStore {
   load(storageKey: string): Promise<IFlexScopeSnapshot | undefined>;
   save(
@@ -617,6 +733,7 @@ export interface IFlexHarnessStores {
   scopes: IFlexScopeStore;
   projections: IFlexProjectionStore;
   permissions: IFlexPermissionStore;
+  projectManagement: IFlexProjectManagementStore;
   agentEvents: IFlexAgentEventStoreProvider;
   jobs: IFlexToolJobStoreProvider;
 }
@@ -875,6 +992,17 @@ export interface IFlexSubagentDefinition {
   maxSteps?: number;
 }
 
+export interface IFlexProjectManagementBuiltInToolsOptions {
+  task?: boolean;
+  goal?: boolean;
+  scratchpad?: boolean;
+}
+
+export interface IFlexBuiltInToolsOptions {
+  renameSession?: boolean;
+  projectManagement?: IFlexProjectManagementBuiltInToolsOptions;
+}
+
 export interface IFlexHarnessOptions<TScope> {
   scopeResolver: IFlexScopeResolver<TScope>;
   modelResolver: IFlexModelResolver<TScope>;
@@ -891,6 +1019,7 @@ export interface IFlexHarnessOptions<TScope> {
   reversionPolicy?: TFlexReversionPolicy;
   externalErrorProjector?: TFlexExternalErrorProjector;
   subagents?: IFlexSubagentDefinition[];
+  builtInTools?: IFlexBuiltInToolsOptions;
   slashCommands?: readonly TFlexSlashCommandRegistration<TScope>[];
   maxSubagentDepth?: number;
   maxSubagentCallsPerRun?: number;

package/ts/utils.json.ts

@@ -6,6 +6,7 @@ import {
   FLEX_REVERSION_REFERENCE_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
+  FLEX_SESSION_GENERATION_ID_MAX_BYTES,
 } from './interfaces.js';
 import type {
   IFlexJsonLimits,
@@ -432,6 +433,39 @@ const activityStatuses = [
   'cancelled',
 ] as const;
 
+function validateOptionalSessionGeneration(
+  value: Record<string, unknown>,
+  path: string,
+): { sessionGenerationId?: string; sessionGenerationSequence?: number } {
+  const hasId = value.sessionGenerationId !== undefined;
+  const hasSequence = value.sessionGenerationSequence !== undefined;
+  if (hasId !== hasSequence) {
+    throw new FlexHarnessStoreFormatError(`${path} has partial session generation fields.`);
+  }
+  if (!hasId) return {};
+  const sessionGenerationId = requireString(
+    value.sessionGenerationId,
+    `${path}.sessionGenerationId`,
+  );
+  if (Buffer.byteLength(sessionGenerationId, 'utf8') > FLEX_SESSION_GENERATION_ID_MAX_BYTES) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.sessionGenerationId exceeds ${FLEX_SESSION_GENERATION_ID_MAX_BYTES} UTF-8 bytes.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(value.sessionGenerationSequence)
+    || Number(value.sessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.sessionGenerationSequence must be a positive integer.`,
+    );
+  }
+  return {
+    sessionGenerationId,
+    sessionGenerationSequence: value.sessionGenerationSequence as number,
+  };
+}
+
 function validateSession(value: unknown, path: string): IValidatedSessionIdentity {
   const session = requireRecord(value, path);
   requireOnlyKeys(
@@ -439,6 +473,8 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     [
       'scopeId',
       'sessionId',
+      'sessionGenerationId',
+      'sessionGenerationSequence',
       'title',
       'createdAt',
       'updatedAt',
@@ -455,6 +491,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   );
   requireString(session.scopeId, `${path}.scopeId`);
   const sessionId = requireString(session.sessionId, `${path}.sessionId`);
+  const generation = validateOptionalSessionGeneration(session, path);
   requireOptionalString(session.title, `${path}.title`);
   requireString(session.createdAt, `${path}.createdAt`);
   requireString(session.updatedAt, `${path}.updatedAt`);
@@ -496,6 +533,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   }
   return {
     sessionId,
+    ...generation,
     ...(relationshipCount === 0
       ? {}
       : {
@@ -541,6 +579,8 @@ interface IValidatedMessageIdentity {
 
 interface IValidatedSessionIdentity {
   sessionId: string;
+  sessionGenerationId?: string;
+  sessionGenerationSequence?: number;
   parentSessionId?: string;
   parentRunId?: string;
   parentToolCallId?: string;
@@ -780,10 +820,19 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
     const tombstone = requireRecord(snapshot.tombstones[index], path);
     requireOnlyKeys(
       tombstone,
-      ['sessionId', 'deletedAt', 'rootSessionId', 'depth', 'parentSessionId'],
+      [
+        'sessionId',
+        'sessionGenerationId',
+        'sessionGenerationSequence',
+        'deletedAt',
+        'rootSessionId',
+        'depth',
+        'parentSessionId',
+      ],
       path,
     );
     const sessionId = requireString(tombstone.sessionId, `${path}.sessionId`);
+    validateOptionalSessionGeneration(tombstone, path);
     requireString(tombstone.deletedAt, `${path}.deletedAt`);
     const parentSessionId = tombstone.parentSessionId === undefined
       ? undefined