@modelprofile.com/flexharness 5.1.0 → 5.3.0

package/ts/interfaces.ts

@@ -155,6 +155,7 @@ export interface IFlexSession {
 
 export interface IFlexCreateSessionOptions {
   sessionId?: string;
+  sessionGenerationId?: string;
   title?: string;
 }
 
@@ -342,7 +343,7 @@ export interface IFlexScopeResolver<TScope> {
   resolveScope(scopeId: string): Promise<IFlexResolvedScope<TScope>> | IFlexResolvedScope<TScope>;
 }
 
-export interface IFlexModelResolverContext<TScope> {
+export interface IFlexModelResolverContext<TScope> extends IFlexSessionGeneration {
   scopeId: string;
   scope: TScope;
   sessionId: string;
@@ -376,7 +377,8 @@ export interface IFlexPermissionRequestInput {
   metadata?: TJsonValue;
 }
 
-export interface IFlexPermissionRequest extends IFlexPermissionRequestInput {
+export interface IFlexPermissionRequest
+  extends IFlexPermissionRequestInput, IFlexSessionGeneration {
   permissionId: string;
   scopeId: string;
   sessionId: string;
@@ -573,12 +575,27 @@ export interface IFlexPermissionSnapshot {
 
 export const FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION = 1 as const;
 export const FLEX_SESSION_GENERATION_ID_MAX_BYTES = 128;
+export const FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES = 2048;
 
 export interface IFlexSessionGeneration {
   sessionGenerationId: string;
   sessionGenerationSequence: number;
 }
 
+export interface IFlexSessionGenerationCohortEntry extends IFlexSessionGeneration {
+  sessionId: string;
+}
+
+export interface IFlexDeleteSessionGenerationCohortInput {
+  root: IFlexSessionGenerationCohortEntry;
+  /** Exact authorized entries ordered by strictly ascending sessionId. */
+  authorizedCohort: readonly IFlexSessionGenerationCohortEntry[];
+}
+
+export interface IFlexDeleteSessionGenerationCohortResult {
+  readonly matched: boolean;
+}
+
 export const FLEX_PROJECT_MANAGEMENT_LIMITS = Object.freeze({
   maxGoalBytes: 8 * 1024,
   maxScratchpadBytes: 128 * 1024,
@@ -927,6 +944,7 @@ export interface IFlexRedoSessionResult {
 export type TFlexExternalErrorSource =
   | 'modelResolver'
   | 'toolProvider'
+  | 'delegatedRunAdmissionProvider'
   | 'toolExecution'
   | 'toolCallback'
   | 'toolCleanup'
@@ -947,6 +965,37 @@ export type TFlexExternalErrorProjector = (
   context: IFlexExternalErrorContext,
 ) => IFlexErrorInfo;
 
+export interface IFlexDelegatedRunAdmissionContext<TScope> extends IFlexSessionGeneration {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly sessionGenerationId: string;
+  readonly sessionGenerationSequence: number;
+  readonly queueId: string;
+  readonly runId: string;
+  readonly parentSessionId: string;
+  readonly parentSessionGenerationId: string;
+  readonly parentSessionGenerationSequence: number;
+  readonly parentQueueId: string;
+  readonly parentRunId: string;
+  readonly parentToolCallId: string;
+  readonly agent: string;
+  readonly depth: number;
+  readonly signal: AbortSignal;
+}
+
+export interface IFlexDelegatedRunAdmissionLease {
+  /** Must be idempotent and safe to retry after a rejected close attempt. */
+  close(): Promise<void> | void;
+}
+
+export interface IFlexDelegatedRunAdmissionProvider<TScope> {
+  acquireDelegatedRunAdmission(
+    context: IFlexDelegatedRunAdmissionContext<TScope>,
+  ): Promise<IFlexDelegatedRunAdmissionLease> | IFlexDelegatedRunAdmissionLease;
+}
+
 export interface IFlexExecutionContextProviderContext<TScope> {
   scopeId: string;
   scope: TScope;
@@ -1018,6 +1067,7 @@ export interface IFlexHarnessOptions<TScope> {
   toolProvider?: IFlexToolProvider<TScope>;
   resourceToolProviderResolver?: IFlexResourceToolProviderResolver<TScope>;
   executionContextProvider?: IFlexExecutionContextProvider<TScope>;
+  delegatedRunAdmissionProvider?: IFlexDelegatedRunAdmissionProvider<TScope>;
   stores?: IFlexHarnessStores;
   agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
   toolOutputLimits?: IFlexJsonLimits;
@@ -1070,7 +1120,7 @@ export interface IFlexEventArchiveMetadata {
   eventCount: number;
 }
 
-export interface IFlexEventBase {
+export interface IFlexEventBase extends IFlexSessionGeneration {
   readonly eventId: string;
   readonly sequence: number;
   readonly timestamp: string;

package/ts/utils.validation.ts

@@ -1,9 +1,15 @@
 import { FlexHarnessValidationError } from './errors.js';
-import { FLEX_PROJECT_MANAGEMENT_LIMITS } from './interfaces.js';
+import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
+  FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES,
+  FLEX_SESSION_GENERATION_ID_MAX_BYTES,
+} from './interfaces.js';
 import type {
   IFlexCreateProjectTaskInput,
+  IFlexDeleteSessionGenerationCohortInput,
   IFlexErrorInfo,
   IFlexPromptOptions,
+  IFlexSessionGenerationCohortEntry,
   IFlexSlashCommandExecutionOptions,
   IFlexUpdateProjectTaskInput,
   IFlexUpdateSessionOptions,
@@ -14,6 +20,7 @@ import type {
 const maxProjectedErrorNameBytes = 128;
 const maxProjectedErrorMessageBytes = 2048;
 const maxProjectedErrorCodeBytes = 128;
+const controlCharacterPattern = /[\u0000-\u001f\u007f]/u;
 
 export function validateIdentifier(value: string, name: string): void {
   if (typeof value !== 'string' || value.length === 0) {
@@ -38,6 +45,123 @@ export function validateUtf8String(
   }
 }
 
+export function validateSessionGenerationId(
+  value: unknown,
+  name = 'sessionGenerationId',
+): asserts value is string {
+  if (
+    typeof value !== 'string'
+    || !value.trim()
+    || Buffer.byteLength(value, 'utf8') > FLEX_SESSION_GENERATION_ID_MAX_BYTES
+    || controlCharacterPattern.test(value)
+  ) {
+    throw new FlexHarnessValidationError(
+      `${name} must be a non-empty string without control characters of at most ${FLEX_SESSION_GENERATION_ID_MAX_BYTES} UTF-8 bytes.`,
+    );
+  }
+}
+
+function validateSessionGenerationSequence(value: unknown, name: string): asserts value is number {
+  if (!Number.isSafeInteger(value) || Number(value) < 1) {
+    throw new FlexHarnessValidationError(`${name} must be a positive integer.`);
+  }
+}
+
+function validateSessionGenerationCohortEntry(
+  value: unknown,
+  name: string,
+): Readonly<IFlexSessionGenerationCohortEntry> {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessValidationError(`${name} must be a plain object.`);
+  }
+  const entry = value as Record<string, unknown>;
+  const keys = Reflect.ownKeys(entry);
+  if (
+    keys.length !== 3
+    || keys.some((key) => typeof key !== 'string'
+      || !['sessionId', 'sessionGenerationId', 'sessionGenerationSequence'].includes(key))
+  ) {
+    throw new FlexHarnessValidationError(`${name} must use the exact session generation shape.`);
+  }
+  validateIdentifier(entry.sessionId as string, `${name}.sessionId`);
+  validateSessionGenerationId(entry.sessionGenerationId, `${name}.sessionGenerationId`);
+  validateSessionGenerationSequence(
+    entry.sessionGenerationSequence,
+    `${name}.sessionGenerationSequence`,
+  );
+  return Object.freeze({
+    sessionId: entry.sessionId as string,
+    sessionGenerationId: entry.sessionGenerationId,
+    sessionGenerationSequence: entry.sessionGenerationSequence,
+  });
+}
+
+export function validateDeleteSessionGenerationCohortInput(
+  value: IFlexDeleteSessionGenerationCohortInput,
+): {
+    root: Readonly<IFlexSessionGenerationCohortEntry>;
+    authorizedBySessionId: ReadonlyMap<string, Readonly<IFlexSessionGenerationCohortEntry>>;
+  } {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessValidationError(
+      'deleteSessionGenerationCohort input must be a plain object.',
+    );
+  }
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.length !== 2
+    || keys.some((key) => typeof key !== 'string'
+      || !['root', 'authorizedCohort'].includes(key))
+  ) {
+    throw new FlexHarnessValidationError(
+      'deleteSessionGenerationCohort input must use the exact root and authorizedCohort shape.',
+    );
+  }
+  const root = validateSessionGenerationCohortEntry(value.root, 'root');
+  if (!Array.isArray(value.authorizedCohort)) {
+    throw new FlexHarnessValidationError('authorizedCohort must be an array.');
+  }
+  if (value.authorizedCohort.length > FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES) {
+    throw new FlexHarnessValidationError(
+      `authorizedCohort exceeds ${FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES} entries.`,
+    );
+  }
+  const authorizedBySessionId = new Map<
+    string,
+    Readonly<IFlexSessionGenerationCohortEntry>
+  >();
+  let previousSessionId: string | undefined;
+  for (const [index, rawEntry] of value.authorizedCohort.entries()) {
+    const entry = validateSessionGenerationCohortEntry(
+      rawEntry,
+      `authorizedCohort[${index}]`,
+    );
+    if (authorizedBySessionId.has(entry.sessionId)) {
+      throw new FlexHarnessValidationError(
+        `authorizedCohort contains duplicate sessionId "${entry.sessionId}".`,
+      );
+    }
+    if (previousSessionId !== undefined && previousSessionId >= entry.sessionId) {
+      throw new FlexHarnessValidationError(
+        'authorizedCohort must be ordered by strictly ascending sessionId.',
+      );
+    }
+    authorizedBySessionId.set(entry.sessionId, entry);
+    previousSessionId = entry.sessionId;
+  }
+  return { root, authorizedBySessionId };
+}
+
 export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
   if (
     !value