@modelprofile.com/flexharness 9.4.0 → 9.6.0

package/ts/utils.sessionimport.ts

@@ -0,0 +1,327 @@
+import { FlexHarnessValidationError } from './errors.js';
+import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
+  FLEX_SESSION_IMPORT_DEFAULT_LIMITS,
+  FLEX_SESSION_IMPORT_MAXIMUM_LIMITS,
+  FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES,
+  FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES,
+} from './interfaces.js';
+import type {
+  IFlexBeginSessionImportOptions,
+  IFlexImportedRun,
+  IFlexMessage,
+  IFlexSessionImportHandle,
+  IFlexSessionImportLimits,
+  IFlexSessionImportParent,
+  IFlexSessionImportPart,
+  IFlexSessionImportSource,
+  IJsonObject,
+} from './interfaces.js';
+import { maxSubagentNameBytes } from './utils.harnessoptions.js';
+import { assertFlexMessageRecord, assertJsonSerializable, cloneSerializable } from './utils.json.js';
+import {
+  createBoundedTransferMessage,
+  jsonBytes,
+  maxTransferIdentifierBytes,
+  requireTransferIdentifier,
+} from './utils.transfer.js';
+import { validateIdentifier, validateUtf8String } from './utils.validation.js';
+
+const maxSourceBytes = 128;
+const maxDigestBytes = 256;
+const maxImportParts = 1024;
+const controlCharacterPattern = /[\u0000-\u001f\u007f]/u;
+
+export interface INormalizedSessionImportOptions {
+  sessionId: string;
+  title?: string;
+  createdAt: string;
+  updatedAt: string;
+  origin: IFlexSessionImportSource;
+  parent?: IFlexSessionImportParent;
+}
+
+export interface INormalizedImportedRunPage {
+  runs: IFlexImportedRun[];
+  bytes: number;
+}
+
+export function resolveSessionImportLimits(
+  limits: IFlexSessionImportLimits = {},
+): Required<IFlexSessionImportLimits> {
+  const resolved = {
+    maxOpenImports: limits.maxOpenImports ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxOpenImports,
+    maxMessagesPerSession: limits.maxMessagesPerSession
+      ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxMessagesPerSession,
+    maxSessionBytes: limits.maxSessionBytes ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxSessionBytes,
+    maxPageBytes: limits.maxPageBytes ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxPageBytes,
+    stagedImportIdleTimeoutMs: limits.stagedImportIdleTimeoutMs
+      ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.stagedImportIdleTimeoutMs,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    const maximum = FLEX_SESSION_IMPORT_MAXIMUM_LIMITS[name as keyof IFlexSessionImportLimits];
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+      throw new FlexHarnessValidationError(
+        `sessionImportLimits.${name} must be an integer from 1 through ${maximum}.`,
+      );
+    }
+  }
+  return resolved;
+}
+
+function requirePlainRecord(value: unknown, name: string): Record<string, unknown> {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessValidationError(`${name} must be a plain object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireKnownKeys(
+  record: Record<string, unknown>,
+  allowedKeys: readonly string[],
+  name: string,
+): void {
+  const unsupported = Reflect.ownKeys(record).find((key) =>
+    typeof key !== 'string' || !allowedKeys.includes(key));
+  if (unsupported !== undefined) {
+    throw new FlexHarnessValidationError(`${name} does not support "${String(unsupported)}".`);
+  }
+}
+
+function requireBoundedText(value: unknown, name: string, maxBytes: number): string {
+  validateUtf8String(value, name, maxBytes, true);
+  if (controlCharacterPattern.test(value)) {
+    throw new FlexHarnessValidationError(`${name} must not contain control characters.`);
+  }
+  return value;
+}
+
+/** A timestamp exactly as `Date.prototype.toISOString()` renders it. */
+export function requireCanonicalTimestamp(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value.length > 64) {
+    throw new FlexHarnessValidationError(`${name} must be an ISO 8601 timestamp.`);
+  }
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+    throw new FlexHarnessValidationError(
+      `${name} must be an ISO 8601 timestamp as Date.prototype.toISOString() renders it.`,
+    );
+  }
+  return value;
+}
+
+function normalizeImportPart(value: unknown): IFlexSessionImportPart {
+  const part = requirePlainRecord(value, 'origin.part');
+  requireKnownKeys(part, ['index', 'count'], 'origin.part');
+  const { index, count } = part;
+  if (
+    !Number.isSafeInteger(count)
+    || Number(count) < 1
+    || Number(count) > maxImportParts
+    || !Number.isSafeInteger(index)
+    || Number(index) < 0
+    || Number(index) >= Number(count)
+  ) {
+    throw new FlexHarnessValidationError(
+      `origin.part must have a count from 1 through ${maxImportParts} and a zero-based index below it.`,
+    );
+  }
+  return { index: index as number, count: count as number };
+}
+
+function normalizeImportDetails(value: unknown): IJsonObject {
+  requirePlainRecord(value, 'origin.details');
+  try {
+    assertJsonSerializable(value, 'origin.details');
+  } catch (error) {
+    throw new FlexHarnessValidationError('origin.details must be a JSON object.', { cause: error });
+  }
+  if (jsonBytes(value) > FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES) {
+    throw new FlexHarnessValidationError(
+      `origin.details must be at most ${FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES} JSON bytes.`,
+    );
+  }
+  return cloneSerializable(value as IJsonObject);
+}
+
+function normalizeImportSource(value: unknown): IFlexSessionImportSource {
+  const origin = requirePlainRecord(value, 'origin');
+  requireKnownKeys(origin, ['source', 'sourceId', 'digest', 'part', 'details'], 'origin');
+  return {
+    source: requireBoundedText(origin.source, 'origin.source', maxSourceBytes),
+    sourceId: requireBoundedText(origin.sourceId, 'origin.sourceId', maxTransferIdentifierBytes),
+    digest: requireBoundedText(origin.digest, 'origin.digest', maxDigestBytes),
+    ...(origin.part === undefined ? {} : { part: normalizeImportPart(origin.part) }),
+    ...(origin.details === undefined ? {} : { details: normalizeImportDetails(origin.details) }),
+  };
+}
+
+function normalizeImportParent(value: unknown): IFlexSessionImportParent {
+  const parent = requirePlainRecord(value, 'parent');
+  requireKnownKeys(parent, ['sessionId', 'runId', 'toolCallId', 'agent'], 'parent');
+  return {
+    sessionId: requireBoundedText(parent.sessionId, 'parent.sessionId', maxTransferIdentifierBytes),
+    runId: requireBoundedText(parent.runId, 'parent.runId', maxTransferIdentifierBytes),
+    toolCallId: requireBoundedText(parent.toolCallId, 'parent.toolCallId', maxTransferIdentifierBytes),
+    agent: requireBoundedText(parent.agent, 'parent.agent', maxSubagentNameBytes),
+  };
+}
+
+export function normalizeBeginSessionImportOptions(
+  options: IFlexBeginSessionImportOptions,
+): INormalizedSessionImportOptions {
+  const record = requirePlainRecord(options, 'beginSessionImport options');
+  requireKnownKeys(
+    record,
+    ['sessionId', 'title', 'createdAt', 'updatedAt', 'origin', 'parent'],
+    'beginSessionImport options',
+  );
+  const sessionId = record.sessionId as string;
+  validateIdentifier(sessionId, 'sessionId');
+  requireTransferIdentifier(sessionId, 'sessionId');
+  if (record.title !== undefined) {
+    validateUtf8String(record.title, 'title', FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes, true);
+  }
+  const createdAt = requireCanonicalTimestamp(record.createdAt, 'createdAt');
+  const updatedAt = record.updatedAt === undefined
+    ? createdAt
+    : requireCanonicalTimestamp(record.updatedAt, 'updatedAt');
+  if (Date.parse(updatedAt) < Date.parse(createdAt)) {
+    throw new FlexHarnessValidationError('updatedAt must not be earlier than createdAt.');
+  }
+  const parent = record.parent === undefined ? undefined : normalizeImportParent(record.parent);
+  if (parent?.sessionId === sessionId) {
+    throw new FlexHarnessValidationError('An imported session cannot be its own parent.');
+  }
+  return {
+    sessionId,
+    ...(record.title === undefined ? {} : { title: record.title as string }),
+    createdAt,
+    updatedAt,
+    origin: normalizeImportSource(record.origin),
+    ...(parent === undefined ? {} : { parent }),
+  };
+}
+
+/** The identity an import is idempotent by: its source, source id and part. */
+export function sessionImportIdentity(
+  origin: Pick<IFlexSessionImportSource, 'source' | 'sourceId' | 'part'>,
+): string {
+  return JSON.stringify([origin.source, origin.sourceId, origin.part?.index ?? null]);
+}
+
+function normalizeImportedMessage(
+  value: unknown,
+  path: string,
+  role: IFlexMessage['role'],
+  sessionId: string,
+): { message: IFlexMessage; bytes: number } {
+  try {
+    assertFlexMessageRecord(value, path);
+  } catch (error) {
+    throw new FlexHarnessValidationError(
+      `${path} is not a valid message: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  const message = cloneSerializable(value as IFlexMessage);
+  if (message.role !== role) {
+    throw new FlexHarnessValidationError(`${path}.role must be "${role}".`);
+  }
+  if (message.sessionId !== sessionId) {
+    throw new FlexHarnessValidationError(`${path}.sessionId must be the imported session "${sessionId}".`);
+  }
+  if (message.status === 'streaming') {
+    throw new FlexHarnessValidationError(`${path}.status must be completed, failed or cancelled.`);
+  }
+  requireCanonicalTimestamp(message.createdAt, `${path}.createdAt`);
+  if (message.completedAt !== undefined) {
+    requireCanonicalTimestamp(message.completedAt, `${path}.completedAt`);
+  }
+  for (const [index, part] of message.parts.entries()) {
+    if (part.type !== 'reasoning' && part.type !== 'tool') continue;
+    if (part.status === 'running') {
+      throw new FlexHarnessValidationError(`${path}.parts[${index}] must not be running.`);
+    }
+  }
+  const bytes = jsonBytes(message);
+  if (bytes > FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES) {
+    throw new FlexHarnessValidationError(
+      `${path} exceeds ${FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES} JSON bytes.`,
+    );
+  }
+  try {
+    createBoundedTransferMessage(message);
+  } catch (error) {
+    throw new FlexHarnessValidationError(`${path} cannot be read back within the transfer limits.`, {
+      cause: error,
+    });
+  }
+  return { message, bytes };
+}
+
+/**
+ * Validates one page of imported runs. Every message must belong to `sessionId`, be terminal and
+ * fit the transfer limits; a run's user and assistant message share its run id and status.
+ */
+export function normalizeImportedRunPage(
+  runs: readonly IFlexImportedRun[],
+  sessionId: string,
+  maxPageBytes: number,
+): INormalizedImportedRunPage {
+  if (!Array.isArray(runs) || runs.length === 0) {
+    throw new FlexHarnessValidationError('Imported runs must be a non-empty array.');
+  }
+  let pageBytes: number;
+  try {
+    assertJsonSerializable(runs, 'runs');
+    pageBytes = jsonBytes(runs);
+  } catch (error) {
+    throw new FlexHarnessValidationError('Imported runs must be JSON-safe.', { cause: error });
+  }
+  if (pageBytes > maxPageBytes) {
+    throw new FlexHarnessValidationError(`Imported runs exceed the page limit of ${maxPageBytes} JSON bytes.`);
+  }
+  const normalized: IFlexImportedRun[] = [];
+  let bytes = 0;
+  for (const [index, value] of runs.entries()) {
+    const path = `runs[${index}]`;
+    const run = requirePlainRecord(value, path);
+    requireKnownKeys(run, ['user', 'assistant'], path);
+    const user = normalizeImportedMessage(run.user, `${path}.user`, 'user', sessionId);
+    const assistant = normalizeImportedMessage(run.assistant, `${path}.assistant`, 'assistant', sessionId);
+    if (user.message.runId !== assistant.message.runId) {
+      throw new FlexHarnessValidationError(`${path} user and assistant messages must share one runId.`);
+    }
+    if (user.message.messageId === assistant.message.messageId) {
+      throw new FlexHarnessValidationError(`${path} user and assistant messages must have distinct ids.`);
+    }
+    if (user.message.status !== assistant.message.status) {
+      throw new FlexHarnessValidationError(`${path} user and assistant messages must share one status.`);
+    }
+    normalized.push({ user: user.message, assistant: assistant.message });
+    bytes += user.bytes + assistant.bytes;
+  }
+  return { runs: normalized, bytes };
+}
+
+/** Validates the shape of a handle `beginSessionImport()` returned. */
+export function validateSessionImportHandle(handle: IFlexSessionImportHandle): IFlexSessionImportHandle {
+  const record = requirePlainRecord(handle, 'Session import handle');
+  requireKnownKeys(record, ['importId', 'scopeId', 'sessionId'], 'Session import handle');
+  for (const key of ['importId', 'scopeId', 'sessionId'] as const) {
+    if (typeof record[key] !== 'string' || record[key] === '') {
+      throw new FlexHarnessValidationError(`Session import handle ${key} must be a non-empty string.`);
+    }
+  }
+  return {
+    importId: record.importId as string,
+    scopeId: record.scopeId as string,
+    sessionId: record.sessionId as string,
+  };
+}