@modelprofile.com/flexharness 4.0.2 → 4.1.1

package/ts/classes.stores.ts

@@ -34,6 +34,16 @@ import {
   assertFlexProjectManagementSnapshot,
   assertFlexProjectManagementTombstone,
 } from './utils.projectmanagement.js';
+import {
+  assertExactKeys,
+  assertRecord,
+  createAgentEventSnapshot,
+  createToolJobSnapshot,
+  normalizeJsonObjectUndefined,
+  validateAgentEventArchive,
+  validateAgentEventSnapshot,
+  validateToolJobSnapshot,
+} from './utils.storecodecs.js';
 
 type TSnapshot =
   | IFlexScopeSnapshot
@@ -130,249 +140,6 @@ function assertProjectionSession(snapshot: TFlexProjectionSnapshot, sessionId: s
   }
 }
 
-function normalizeJsonObjectUndefined<TValue>(value: TValue, path = '$'): TValue {
-  const seen = new WeakSet<object>();
-  const visit = (current: unknown, currentPath: string): unknown => {
-    if (
-      current === null
-      || typeof current === 'string'
-      || typeof current === 'boolean'
-    ) return current;
-    if (typeof current === 'number') {
-      if (!Number.isFinite(current)) {
-        throw new FlexHarnessStoreFormatError(`${currentPath} contains a non-finite number.`);
-      }
-      return current;
-    }
-    if (typeof current !== 'object') {
-      throw new FlexHarnessStoreFormatError(
-        `${currentPath} contains ${typeof current}, which is not JSON-safe.`,
-      );
-    }
-    if (seen.has(current)) {
-      throw new FlexHarnessStoreFormatError(`${currentPath} contains a circular reference.`);
-    }
-    const prototype = Object.getPrototypeOf(current);
-    if (!Array.isArray(current) && prototype !== Object.prototype && prototype !== null) {
-      throw new FlexHarnessStoreFormatError(`${currentPath} contains a non-plain object.`);
-    }
-    if (Object.getOwnPropertySymbols(current).length > 0) {
-      throw new FlexHarnessStoreFormatError(`${currentPath} contains a symbol-keyed property.`);
-    }
-    seen.add(current);
-    if (Array.isArray(current)) {
-      const result = current.map((entry, index) => {
-        if (!(index in current) || entry === undefined) {
-          throw new FlexHarnessStoreFormatError(`${currentPath}[${index}] is not JSON-safe.`);
-        }
-        return visit(entry, `${currentPath}[${index}]`);
-      });
-      seen.delete(current);
-      return result;
-    }
-    const result: Record<string, unknown> = {};
-    for (const key of Object.getOwnPropertyNames(current)) {
-      const descriptor = Object.getOwnPropertyDescriptor(current, key)!;
-      if (!descriptor.enumerable || !('value' in descriptor)) {
-        throw new FlexHarnessStoreFormatError(`${currentPath}.${key} is not a plain JSON property.`);
-      }
-      if (descriptor.value !== undefined) {
-        result[key] = visit(descriptor.value, `${currentPath}.${key}`);
-      }
-    }
-    seen.delete(current);
-    return result;
-  };
-  const normalized = visit(value, path);
-  assertJsonSerializable(normalized, path);
-  return normalized as TValue;
-}
-
-function assertNonEmptyString(value: unknown, path: string): asserts value is string {
-  if (typeof value !== 'string' || !value.trim()) {
-    throw new FlexHarnessStoreFormatError(`${path} must be a non-empty string.`);
-  }
-}
-
-function assertNonNegativeInteger(value: unknown, path: string): asserts value is number {
-  if (!Number.isSafeInteger(value) || Number(value) < 0) {
-    throw new FlexHarnessStoreFormatError(`${path} must be a non-negative integer.`);
-  }
-}
-
-function assertExactKeys(
-  value: Record<string, unknown>,
-  keys: readonly string[],
-  path: string,
-): void {
-  const invalidKey = Object.keys(value).find((key) => !keys.includes(key));
-  if (invalidKey) {
-    throw new FlexHarnessStoreFormatError(`${path}.${invalidKey} is not supported.`);
-  }
-}
-
-function assertRecord(value: unknown, path: string): asserts value is Record<string, unknown> {
-  if (
-    !value
-    || typeof value !== 'object'
-    || Array.isArray(value)
-    || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
-  ) {
-    throw new FlexHarnessStoreFormatError(`${path} must be a plain object.`);
-  }
-}
-
-function createAgentEventSnapshot(
-  sessionId: string,
-  events: readonly plugins.TAgentEvent[],
-  revision: number,
-): plugins.IAgentEventSnapshotV2 {
-  return {
-    schemaVersion: 2,
-    sessionId,
-    revision,
-    updatedAt: events.reduce((latest, event) => Math.max(latest, event.timestamp), 0),
-    events: normalizeJsonObjectUndefined([...events], '$events'),
-  };
-}
-
-function validateAgentEventSnapshot(
-  value: unknown,
-  sessionId: string,
-): plugins.IAgentEventSnapshotV2 {
-  assertJsonSerializable(value, '$snapshot');
-  try {
-    return plugins.validateAgentEventSnapshotV2(value, sessionId);
-  } catch (error) {
-    throw new FlexHarnessStoreFormatError(
-      `$snapshot is not a canonical schema-2 Agent event snapshot: ${error instanceof Error ? error.message : String(error)}`,
-      { cause: error },
-    );
-  }
-}
-
-function validateAgentEventArchive(
-  value: unknown,
-  sessionId: string,
-  archiveId: string,
-): plugins.IAgentEventArchiveV2 {
-  assertJsonSerializable(value, '$archive');
-  try {
-    return plugins.validateAgentEventArchiveV2(value, sessionId, archiveId);
-  } catch (error) {
-    throw new FlexHarnessStoreFormatError(
-      `$archive is not a canonical schema-2 Agent event archive: ${error instanceof Error ? error.message : String(error)}`,
-      { cause: error },
-    );
-  }
-}
-
-function validateToolJobSnapshot(value: unknown): plugins.IToolJobSnapshot {
-  assertJsonSerializable(value, '$snapshot');
-  assertRecord(value, '$snapshot');
-  assertExactKeys(value, ['schemaVersion', 'revision', 'updatedAt', 'jobs'], '$snapshot');
-  if (value.schemaVersion !== 1) {
-    throw new FlexHarnessStoreFormatError('Tool job snapshot schemaVersion must be 1.');
-  }
-  assertNonNegativeInteger(value.revision, '$snapshot.revision');
-  assertNonNegativeInteger(value.updatedAt, '$snapshot.updatedAt');
-  if (!Array.isArray(value.jobs)) {
-    throw new FlexHarnessStoreFormatError('$snapshot.jobs must be an array.');
-  }
-  const executionIds = new Set<string>();
-  for (let index = 0; index < value.jobs.length; index++) {
-    const path = `$snapshot.jobs[${index}]`;
-    assertRecord(value.jobs[index], path);
-    const job = value.jobs[index];
-    assertExactKeys(
-      job,
-      [
-        'executionId',
-        'type',
-        'state',
-        'request',
-        'exitCode',
-        'stdout',
-        'stderr',
-        'signal',
-        'startedAt',
-        'updatedAt',
-        'finishedAt',
-      ],
-      path,
-    );
-    assertNonEmptyString(job.executionId, `${path}.executionId`);
-    if (executionIds.has(job.executionId)) {
-      throw new FlexHarnessStoreFormatError(`$snapshot.jobs contains duplicate job "${job.executionId}".`);
-    }
-    executionIds.add(job.executionId);
-    assertNonEmptyString(job.type, `${path}.type`);
-    if (!['running', 'finished', 'failed', 'aborted'].includes(String(job.state))) {
-      throw new FlexHarnessStoreFormatError(`${path}.state is invalid.`);
-    }
-    if (job.request !== undefined) {
-      const requestPath = `${path}.request`;
-      assertRecord(job.request, requestPath);
-      assertExactKeys(
-        job.request,
-        ['type', 'command', 'cwd', 'timeoutMs', 'metadata'],
-        requestPath,
-      );
-      assertNonEmptyString(job.request.type, `${requestPath}.type`);
-      if (job.request.command !== undefined) {
-        const commandPath = `${requestPath}.command`;
-        assertRecord(job.request.command, commandPath);
-        assertExactKeys(job.request.command, ['executable', 'args'], commandPath);
-        assertNonEmptyString(job.request.command.executable, `${commandPath}.executable`);
-        if (!Array.isArray(job.request.command.args)) {
-          throw new FlexHarnessStoreFormatError(`${commandPath}.args must be an array.`);
-        }
-        for (let argumentIndex = 0; argumentIndex < job.request.command.args.length; argumentIndex++) {
-          if (typeof job.request.command.args[argumentIndex] !== 'string') {
-            throw new FlexHarnessStoreFormatError(
-              `${commandPath}.args[${argumentIndex}] must be a string.`,
-            );
-          }
-        }
-      }
-      if (job.request.cwd !== undefined && typeof job.request.cwd !== 'string') {
-        throw new FlexHarnessStoreFormatError(`${requestPath}.cwd must be a string.`);
-      }
-      if (job.request.timeoutMs !== undefined) {
-        assertNonNegativeInteger(job.request.timeoutMs, `${requestPath}.timeoutMs`);
-      }
-      if (job.request.metadata !== undefined) {
-        assertRecord(job.request.metadata, `${requestPath}.metadata`);
-      }
-    }
-    if (job.exitCode !== undefined && job.exitCode !== null && !Number.isSafeInteger(job.exitCode)) {
-      throw new FlexHarnessStoreFormatError(`${path}.exitCode must be an integer or null.`);
-    }
-    for (const key of ['stdout', 'stderr', 'signal'] as const) {
-      if (job[key] !== undefined && typeof job[key] !== 'string') {
-        throw new FlexHarnessStoreFormatError(`${path}.${key} must be a string.`);
-      }
-    }
-    for (const key of ['startedAt', 'updatedAt', 'finishedAt'] as const) {
-      if (job[key] !== undefined) assertNonNegativeInteger(job[key], `${path}.${key}`);
-    }
-  }
-  return value as unknown as plugins.IToolJobSnapshot;
-}
-
-function createToolJobSnapshot(
-  jobs: readonly plugins.IToolJobState[],
-  revision: number,
-): plugins.IToolJobSnapshot {
-  const snapshot: plugins.IToolJobSnapshot = {
-    schemaVersion: 1,
-    revision,
-    updatedAt: Date.now(),
-    jobs: normalizeJsonObjectUndefined([...jobs], '$jobs'),
-  };
-  return validateToolJobSnapshot(snapshot);
-}
-
 class InMemoryScopeStore implements IFlexScopeStore {
   private readonly snapshots = new Map<string, IFlexScopeSnapshot>();
 

package/ts/interfaces.ts

@@ -16,6 +16,9 @@ export type TFlexAgentModelMessage = ReturnType<plugins.IAgentSession['getModelM
 export type TFlexAgentToolSet = NonNullable<TFlexAgentSessionOptions['tools']>;
 export type TFlexAgentProviderOptions = TFlexAgentSessionOptions['providerOptions'];
 export type TFlexAgentCacheSetting = TFlexAgentSessionOptions['cache'];
+export type TFlexAgentToolCallUpdateEvent = Parameters<
+  NonNullable<TFlexAgentSessionOptions['onToolCallUpdate']>
+>[0];
 export type TFlexAgentToolCallFinishEvent = Parameters<
   NonNullable<TFlexAgentSessionOptions['onToolCallFinish']>
 >[0];

package/ts/plugins.ts

@@ -47,6 +47,7 @@ export type {
   IAgentRunResult,
   IAgentSession,
   IAgentSessionOptions,
+  IAgentToolCallUpdateEvent,
   IAgentRuntimeEventPayload,
   IGenerationBegunEvent,
   IGenerationExecutionCompletedEvent,

package/ts/utils.harnessoptions.ts

@@ -0,0 +1,372 @@
+import { FlexHarnessValidationError } from './errors.js';
+import {
+  FLEX_REVERSION_DEFAULT_LIMITS,
+  FLEX_REVERSION_MAXIMUM_LIMITS,
+} from './interfaces.js';
+import type {
+  IFlexAgentSessionPolicy,
+  IFlexCallbackLimits,
+  IFlexHarnessOptions,
+  IFlexHarnessStores,
+  IFlexPromptQueueLimits,
+  IFlexReversionLimits,
+  IFlexSlashCommandHandlerRegistration,
+  IFlexSlashCommandTemplateRegistration,
+  IFlexSubagentDefinition,
+  TFlexSlashCommandRegistration,
+} from './interfaces.js';
+import {
+  FLEX_SLASH_COMMAND_MAX_INPUT_BYTES,
+  isReservedSlashCommandName,
+  isValidSlashCommandName,
+} from './utils.slashcommands.js';
+import { validateUtf8String } from './utils.validation.js';
+
+export type TRegisteredSlashCommand<TScope> =
+  | Readonly<IFlexSlashCommandTemplateRegistration>
+  | Readonly<IFlexSlashCommandHandlerRegistration<TScope>>;
+
+export interface INormalizedProjectManagementTools {
+  readonly task: boolean;
+  readonly goal: boolean;
+  readonly scratchpad: boolean;
+}
+
+export interface INormalizedBuiltInTools {
+  readonly renameSession: boolean;
+  readonly projectManagement?: INormalizedProjectManagementTools;
+}
+
+const DEFAULT_CALLBACK_LIMITS: Required<IFlexCallbackLimits> = {
+  maxEvents: 10_000,
+  maxOutputBytes: 1024 * 1024,
+  maxParts: 2_000,
+};
+const DEFAULT_PROMPT_QUEUE_LIMITS: Required<IFlexPromptQueueLimits> = {
+  maxOutstandingPromptsPerSession: 16,
+  maxOutstandingBytesPerSession: 64 * 1024 * 1024,
+  maxPendingAdmissions: 64,
+  maxPendingAdmissionBytes: 128 * 1024 * 1024,
+  maxTerminalEntriesPerSession: 64,
+};
+const maxSubagentDefinitions = 32;
+export const maxSubagentNameBytes = 128;
+const maxSubagentDescriptionBytes = 2048;
+const maxSubagentModelHintBytes = 512;
+const maxSubagentSystemBytes = 64 * 1024;
+const maxSlashCommandRegistrations = 128;
+const maxSlashCommandDescriptionBytes = 2048;
+const maxSlashCommandTemplateBytes = FLEX_SLASH_COMMAND_MAX_INPUT_BYTES;
+
+export function normalizeSubagents(
+  definitions: IFlexSubagentDefinition[] | undefined,
+): ReadonlyMap<string, Readonly<IFlexSubagentDefinition>> {
+  if (definitions === undefined) return new Map();
+  if (!Array.isArray(definitions) || definitions.length > maxSubagentDefinitions) {
+    throw new FlexHarnessValidationError(
+      `subagents must be an array with at most ${maxSubagentDefinitions} definitions.`,
+    );
+  }
+  const normalized = new Map<string, Readonly<IFlexSubagentDefinition>>();
+  for (let index = 0; index < definitions.length; index++) {
+    const definition = definitions[index];
+    if (
+      !definition
+      || typeof definition !== 'object'
+      || Array.isArray(definition)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(definition))
+    ) {
+      throw new FlexHarnessValidationError(`subagents[${index}] must be a plain object.`);
+    }
+    const unsupported = Object.keys(definition).find(
+      (key) => !['name', 'description', 'modelHint', 'system', 'maxSteps'].includes(key),
+    );
+    if (unsupported) {
+      throw new FlexHarnessValidationError(`subagents[${index}] does not support "${unsupported}".`);
+    }
+    validateUtf8String(definition.name, `subagents[${index}].name`, maxSubagentNameBytes, true);
+    validateUtf8String(
+      definition.description,
+      `subagents[${index}].description`,
+      maxSubagentDescriptionBytes,
+    );
+    if (definition.modelHint !== undefined) {
+      validateUtf8String(
+        definition.modelHint,
+        `subagents[${index}].modelHint`,
+        maxSubagentModelHintBytes,
+      );
+    }
+    if (definition.system !== undefined) {
+      validateUtf8String(
+        definition.system,
+        `subagents[${index}].system`,
+        maxSubagentSystemBytes,
+      );
+    }
+    if (
+      definition.maxSteps !== undefined
+      && (!Number.isSafeInteger(definition.maxSteps) || definition.maxSteps < 1)
+    ) {
+      throw new FlexHarnessValidationError(`subagents[${index}].maxSteps must be a positive integer.`);
+    }
+    if (normalized.has(definition.name)) {
+      throw new FlexHarnessValidationError(`Duplicate subagent definition "${definition.name}".`);
+    }
+    normalized.set(definition.name, Object.freeze({
+      name: definition.name,
+      description: definition.description,
+      ...(definition.modelHint === undefined ? {} : { modelHint: definition.modelHint }),
+      ...(definition.system === undefined ? {} : { system: definition.system }),
+      ...(definition.maxSteps === undefined ? {} : { maxSteps: definition.maxSteps }),
+    }));
+  }
+  return Object.freeze(normalized);
+}
+
+export function normalizeBuiltInTools(
+  options: IFlexHarnessOptions<unknown>['builtInTools'],
+): INormalizedBuiltInTools {
+  if (options === undefined) return Object.freeze({ renameSession: false });
+  if (
+    !options
+    || typeof options !== 'object'
+    || Array.isArray(options)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(options))
+  ) {
+    throw new FlexHarnessValidationError('builtInTools must be a plain object.');
+  }
+  const unsupported = Object.keys(options)
+    .find((key) => !['renameSession', 'projectManagement'].includes(key));
+  if (unsupported) throw new FlexHarnessValidationError(`builtInTools does not support "${unsupported}".`);
+  if (options.renameSession !== undefined && typeof options.renameSession !== 'boolean') {
+    throw new FlexHarnessValidationError('builtInTools.renameSession must be a boolean.');
+  }
+  const projectManagement = options.projectManagement;
+  if (projectManagement === undefined) {
+    return Object.freeze({ renameSession: options.renameSession ?? false });
+  }
+  if (
+    !projectManagement
+    || typeof projectManagement !== 'object'
+    || Array.isArray(projectManagement)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(projectManagement))
+  ) {
+    throw new FlexHarnessValidationError('builtInTools.projectManagement must be a plain object.');
+  }
+  const unsupportedProjectOption = Object.keys(projectManagement)
+    .find((key) => !['task', 'goal', 'scratchpad'].includes(key));
+  if (unsupportedProjectOption) {
+    throw new FlexHarnessValidationError(
+      `builtInTools.projectManagement does not support "${unsupportedProjectOption}".`,
+    );
+  }
+  for (const key of ['task', 'goal', 'scratchpad'] as const) {
+    if (projectManagement[key] !== undefined && typeof projectManagement[key] !== 'boolean') {
+      throw new FlexHarnessValidationError(`builtInTools.projectManagement.${key} must be a boolean.`);
+    }
+  }
+  return Object.freeze({
+    renameSession: options.renameSession ?? false,
+    projectManagement: Object.freeze({
+      task: projectManagement.task ?? true,
+      goal: projectManagement.goal ?? true,
+      scratchpad: projectManagement.scratchpad ?? true,
+    }),
+  });
+}
+
+export function normalizeSlashCommands<TScope>(
+  registrations: readonly TFlexSlashCommandRegistration<TScope>[] | undefined,
+): ReadonlyMap<string, TRegisteredSlashCommand<TScope>> {
+  if (registrations === undefined) return new Map();
+  if (!Array.isArray(registrations) || registrations.length > maxSlashCommandRegistrations) {
+    throw new FlexHarnessValidationError(
+      `slashCommands must be an array with at most ${maxSlashCommandRegistrations} registrations.`,
+    );
+  }
+  const normalized = new Map<string, TRegisteredSlashCommand<TScope>>();
+  for (let index = 0; index < registrations.length; index++) {
+    const registration = registrations[index];
+    if (
+      !registration
+      || typeof registration !== 'object'
+      || Array.isArray(registration)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(registration))
+    ) {
+      throw new FlexHarnessValidationError(`slashCommands[${index}] must be a plain object.`);
+    }
+    const keys = Object.keys(registration);
+    const hasTemplate = Object.prototype.hasOwnProperty.call(registration, 'template');
+    const hasHandler = Object.prototype.hasOwnProperty.call(registration, 'handler');
+    const supported = hasTemplate
+      ? ['name', 'description', 'template']
+      : ['name', 'description', 'handler'];
+    const unsupported = keys.find((key) => !supported.includes(key));
+    if (unsupported || hasTemplate === hasHandler) {
+      throw new FlexHarnessValidationError(
+        `slashCommands[${index}] must define exactly one of template or handler.`,
+      );
+    }
+    if (typeof registration.name !== 'string' || !isValidSlashCommandName(registration.name)) {
+      throw new FlexHarnessValidationError(`slashCommands[${index}].name is invalid.`);
+    }
+    if (isReservedSlashCommandName(registration.name)) {
+      throw new FlexHarnessValidationError(
+        `Slash command "${registration.name}" is reserved.`,
+      );
+    }
+    if (normalized.has(registration.name)) {
+      throw new FlexHarnessValidationError(`Duplicate slash command "${registration.name}".`);
+    }
+    if (registration.description !== undefined) {
+      validateUtf8String(
+        registration.description,
+        `slashCommands[${index}].description`,
+        maxSlashCommandDescriptionBytes,
+        true,
+      );
+    }
+    if (hasTemplate) {
+      const template = registration.template;
+      validateUtf8String(
+        template,
+        `slashCommands[${index}].template`,
+        maxSlashCommandTemplateBytes,
+        true,
+      );
+      normalized.set(registration.name, Object.freeze({
+        name: registration.name,
+        ...(registration.description === undefined
+          ? {}
+          : { description: registration.description }),
+        template,
+      }));
+    } else {
+      const handler = registration.handler;
+      if (typeof handler !== 'function') {
+        throw new FlexHarnessValidationError(`slashCommands[${index}].handler must be a function.`);
+      }
+      normalized.set(registration.name, Object.freeze({
+        name: registration.name,
+        ...(registration.description === undefined
+          ? {}
+          : { description: registration.description }),
+        handler,
+      }));
+    }
+  }
+  return Object.freeze(normalized);
+}
+
+export function resolveBoundedPositiveInteger(
+  value: number | undefined,
+  name: string,
+  defaultValue: number,
+  maximum: number,
+): number {
+  const resolved = value ?? defaultValue;
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
+    throw new FlexHarnessValidationError(`${name} must be an integer from 1 through ${maximum}.`);
+  }
+  return resolved;
+}
+
+export function resolveCallbackLimits(limits: IFlexCallbackLimits = {}): Required<IFlexCallbackLimits> {
+  const resolved = {
+    maxEvents: limits.maxEvents ?? DEFAULT_CALLBACK_LIMITS.maxEvents,
+    maxOutputBytes: limits.maxOutputBytes ?? DEFAULT_CALLBACK_LIMITS.maxOutputBytes,
+    maxParts: limits.maxParts ?? DEFAULT_CALLBACK_LIMITS.maxParts,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new FlexHarnessValidationError(`callbackLimits.${name} must be a positive integer.`);
+    }
+  }
+  return resolved;
+}
+
+export function resolvePromptQueueLimits(
+  limits: IFlexPromptQueueLimits = {},
+): Required<IFlexPromptQueueLimits> {
+  const resolved = {
+    maxOutstandingPromptsPerSession: limits.maxOutstandingPromptsPerSession
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxOutstandingPromptsPerSession,
+    maxOutstandingBytesPerSession: limits.maxOutstandingBytesPerSession
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxOutstandingBytesPerSession,
+    maxPendingAdmissions: limits.maxPendingAdmissions
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxPendingAdmissions,
+    maxPendingAdmissionBytes: limits.maxPendingAdmissionBytes
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxPendingAdmissionBytes,
+    maxTerminalEntriesPerSession: limits.maxTerminalEntriesPerSession
+      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxTerminalEntriesPerSession,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new FlexHarnessValidationError(`promptQueueLimits.${name} must be a positive integer.`);
+    }
+  }
+  return resolved;
+}
+
+export function resolveReversionLimits(
+  limits: IFlexReversionLimits = {},
+): Required<IFlexReversionLimits> {
+  const resolved = {
+    maxCompletedTurns: limits.maxCompletedTurns ?? FLEX_REVERSION_DEFAULT_LIMITS.maxCompletedTurns,
+    maxSegments: limits.maxSegments ?? FLEX_REVERSION_DEFAULT_LIMITS.maxSegments,
+    maxExcludedRunIds: limits.maxExcludedRunIds ?? FLEX_REVERSION_DEFAULT_LIMITS.maxExcludedRunIds,
+    maxPendingReversionReleases: limits.maxPendingReversionReleases
+      ?? FLEX_REVERSION_DEFAULT_LIMITS.maxPendingReversionReleases,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    const maximum = FLEX_REVERSION_MAXIMUM_LIMITS[name as keyof IFlexReversionLimits];
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+      throw new FlexHarnessValidationError(
+        `reversionLimits.${name} must be an integer from 1 through ${maximum}.`,
+      );
+    }
+  }
+  return resolved;
+}
+
+export function normalizeAgentSessionPolicy<TScope>(
+  policy: IFlexAgentSessionPolicy<TScope> = {},
+): IFlexAgentSessionPolicy<TScope> {
+  return {
+    ...(policy.contextBuilder === undefined ? {} : { contextBuilder: policy.contextBuilder }),
+    ...(policy.contextCompactor === undefined ? {} : { contextCompactor: policy.contextCompactor }),
+    ...(policy.eventRetention === undefined ? {} : { eventRetention: policy.eventRetention }),
+    ...(policy.changeListenerTimeoutMs === undefined
+      ? {}
+      : { changeListenerTimeoutMs: policy.changeListenerTimeoutMs }),
+    ...(policy.maxPendingSessionChanges === undefined
+      ? {}
+      : { maxPendingSessionChanges: policy.maxPendingSessionChanges }),
+    ...(policy.generationLeaseCleanupTimeoutMs === undefined
+      ? {}
+      : { generationLeaseCleanupTimeoutMs: policy.generationLeaseCleanupTimeoutMs }),
+    ...(policy.maxArchivedTransactionTombstones === undefined
+      ? {}
+      : { maxArchivedTransactionTombstones: policy.maxArchivedTransactionTombstones }),
+    ...(policy.maxContextOverflowRetries === undefined
+      ? {}
+      : { maxContextOverflowRetries: policy.maxContextOverflowRetries }),
+  };
+}
+
+export function requireHarnessStores(stores: IFlexHarnessStores): IFlexHarnessStores {
+  const projectManagement = stores?.projectManagement;
+  if (
+    !projectManagement
+    || typeof projectManagement.load !== 'function'
+    || typeof projectManagement.save !== 'function'
+    || typeof projectManagement.tombstoneSession !== 'function'
+    || typeof projectManagement.purgeNamespace !== 'function'
+  ) {
+    throw new FlexHarnessValidationError(
+      'stores.projectManagement requires load/save/tombstoneSession/purgeNamespace methods.',
+    );
+  }
+  return stores;
+}

package/ts/utils.slashcommands.ts

@@ -12,6 +12,7 @@ const slashCommandArgumentsPattern = /(?:\[Image\s+\d+\]|"[^"]*"|'[^']*'|[^\s"']
 const slashCommandQuoteTrimPattern = /^["']|["']$/g;
 const slashCommandPlaceholderPattern = /\$(\d+)/g;
 const slashCommandAllPlaceholderPattern = /\$ARGUMENTS|\$(\d+)/g;
+const reservedSlashCommandNames = new Set(['compact', 'undo', 'redo', 'init']);
 
 export const FLEX_SLASH_COMMAND_INITIALIZE_TEMPLATE = `Create or update \`AGENTS.md\` for this repository.
 
@@ -85,6 +86,10 @@ export function isValidSlashCommandName(name: string): boolean {
   return slashCommandNamePattern.test(name);
 }
 
+export function isReservedSlashCommandName(name: string): boolean {
+  return reservedSlashCommandNames.has(name);
+}
+
 function tokenizeSlashCommandArguments(rawArguments: string): string[] {
   const tokens = rawArguments.match(slashCommandArgumentsPattern) ?? [];
   return tokens.map((token) => token.replace(slashCommandQuoteTrimPattern, ''));