@modelprofile.com/flexharness 4.1.0 → 4.1.2

package/ts/utils.storecodecs.ts

@@ -0,0 +1,246 @@
+import * as plugins from './plugins.js';
+import { FlexHarnessStoreFormatError } from './errors.js';
+import { assertJsonSerializable } from './utils.json.js';
+
+export 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.`);
+  }
+}
+
+export 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.`);
+  }
+}
+
+export 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.`);
+  }
+}
+
+export 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'),
+  };
+}
+
+export 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 },
+    );
+  }
+}
+
+export 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 },
+    );
+  }
+}
+
+export 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;
+}
+
+export 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);
+}

package/ts/utils.tooloutput.ts

@@ -0,0 +1,72 @@
+import type { IFlexHarnessOptions, TFlexAgentToolSet } from './interfaces.js';
+import { normalizeJsonValue } from './utils.json.js';
+
+interface IExecutableToolRecord extends Record<string, unknown> {
+  execute?: (input: unknown, options: unknown) => unknown;
+}
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return Boolean(
+    value
+    && (typeof value === 'object' || typeof value === 'function')
+    && typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function',
+  );
+}
+
+async function* normalizeAsyncIterable(
+  iterable: AsyncIterable<unknown>,
+  limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+  projectError: (error: unknown) => Error,
+): AsyncGenerator<unknown> {
+  try {
+    for await (const value of iterable) yield normalizeJsonValue(value, limits);
+  } catch (error) {
+    throw projectError(error);
+  }
+}
+
+export function wrapToolSet(
+  tools: TFlexAgentToolSet,
+  limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+  projectError: (error: unknown) => Error,
+): TFlexAgentToolSet {
+  const wrapped: Record<string, unknown> = {};
+  for (const [name, tool] of Object.entries(tools)) {
+    const toolRecord = tool as unknown as IExecutableToolRecord;
+    if (typeof toolRecord.execute !== 'function') {
+      wrapped[name] = tool;
+      continue;
+    }
+    const execute = toolRecord.execute;
+    wrapped[name] = {
+      ...toolRecord,
+      execute(input: unknown, options: unknown): unknown {
+        let output: unknown;
+        try {
+          output = execute.call(tool, input, options);
+          if (isAsyncIterable(output)) {
+            return normalizeAsyncIterable(output, limits, projectError);
+          }
+        } catch (error) {
+          throw projectError(error);
+        }
+        return Promise.resolve(output).then(
+          (value) => {
+            try {
+              if (isAsyncIterable(value)) {
+                return normalizeAsyncIterable(value, limits, projectError);
+              }
+              return normalizeJsonValue(value, limits);
+            } catch (error) {
+              throw projectError(error);
+            }
+          },
+          (error: unknown) => {
+            throw projectError(error);
+          },
+        );
+      },
+    };
+  }
+  return wrapped as TFlexAgentToolSet;
+}

package/ts/utils.transfer.ts

@@ -0,0 +1,210 @@
+import { FlexHarnessValidationError } from './errors.js';
+import type {
+  IFlexAttachmentMessagePart,
+  IFlexMessage,
+  IFlexModelIdentity,
+  IFlexResolvedModel,
+  IFlexUsage,
+  TFlexAgentRunResult,
+  TFlexAttachmentSource,
+  TFlexPromptPart,
+} from './interfaces.js';
+import { cloneSerializable, deepFreeze } from './utils.json.js';
+import { validateIdentifier } from './utils.validation.js';
+
+export interface IRunResultProjection {
+  text: string;
+  steps: number;
+  finishReason: string;
+  usage: IFlexUsage;
+}
+
+export const maxMessagePageSize = 50;
+export const maxMessagePageCursorBytes = 4096;
+export const maxTransferIdentifierBytes = 512;
+export const maxTransferMetadataBytes = 2048;
+export const maxTransferTextBytes = 96 * 1024;
+const maxTransferMessageBytes = 480 * 1024;
+export const maxTransferPageBytes = 512 * 1024;
+
+export function publicSnapshot<TValue>(value: TValue): TValue {
+  return deepFreeze(cloneSerializable(value));
+}
+
+export function jsonBytes(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+export function truncateUtf8(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, 'utf8') <= maxBytes) return value;
+  const suffix = ' [truncated]';
+  const suffixBytes = Buffer.byteLength(suffix, 'utf8');
+  let truncated = Buffer.from(value, 'utf8')
+    .subarray(0, Math.max(0, maxBytes - suffixBytes))
+    .toString('utf8')
+    .replace(/\uFFFD$/u, '');
+  while (Buffer.byteLength(`${truncated}${suffix}`, 'utf8') > maxBytes) {
+    truncated = truncated.slice(0, -1);
+  }
+  return `${truncated}${suffix}`;
+}
+
+export function requireTransferIdentifier(value: string, field: string): void {
+  if (Buffer.byteLength(value, 'utf8') > maxTransferIdentifierBytes) {
+    throw new FlexHarnessValidationError(`${field} exceeds the transfer limit.`);
+  }
+}
+
+export function normalizeModelIdentity(identity: IFlexModelIdentity): IFlexModelIdentity {
+  const normalized: IFlexModelIdentity = {
+    provider: identity.provider,
+    model: identity.model,
+    ...(identity.displayName === undefined ? {} : { displayName: identity.displayName }),
+    ...(identity.variant === undefined ? {} : { variant: identity.variant }),
+  };
+  validateIdentifier(normalized.provider, 'model identity provider');
+  validateIdentifier(normalized.model, 'model identity model');
+  if (normalized.displayName !== undefined) {
+    validateIdentifier(normalized.displayName, 'model identity displayName');
+  }
+  if (normalized.variant !== undefined) validateIdentifier(normalized.variant, 'model identity variant');
+  if (
+    Buffer.byteLength(normalized.provider, 'utf8') > maxTransferIdentifierBytes
+    || Buffer.byteLength(normalized.model, 'utf8') > maxTransferIdentifierBytes
+    || (normalized.displayName !== undefined
+      && Buffer.byteLength(normalized.displayName, 'utf8') > maxTransferMetadataBytes)
+    || (normalized.variant !== undefined && Buffer.byteLength(normalized.variant, 'utf8') > 128)
+  ) {
+    throw new FlexHarnessValidationError('Model identity exceeds its transfer limit.');
+  }
+  return normalized;
+}
+
+export function normalizeResolvedModel(resolvedModel: IFlexResolvedModel): IFlexResolvedModel {
+  return {
+    model: resolvedModel.model,
+    identity: normalizeModelIdentity(resolvedModel.identity),
+    ...(resolvedModel.system === undefined ? {} : { system: resolvedModel.system }),
+    ...(resolvedModel.providerOptions === undefined
+      ? {}
+      : { providerOptions: resolvedModel.providerOptions }),
+    ...(resolvedModel.cache === undefined ? {} : { cache: resolvedModel.cache }),
+    ...(resolvedModel.maxSteps === undefined ? {} : { maxSteps: resolvedModel.maxSteps }),
+  };
+}
+
+export function normalizeRunResult(result: TFlexAgentRunResult): IRunResultProjection {
+  const normalized: IRunResultProjection = {
+    text: result.text,
+    steps: result.steps,
+    finishReason: result.finishReason,
+    usage: {
+      inputTokens: result.usage.inputTokens,
+      outputTokens: result.usage.outputTokens,
+      totalTokens: result.usage.totalTokens,
+      cacheReadTokens: result.usage.cacheReadTokens,
+      cacheWriteTokens: result.usage.cacheWriteTokens,
+    },
+  };
+  if (
+    typeof normalized.text !== 'string'
+    || typeof normalized.finishReason !== 'string'
+    || !Number.isSafeInteger(normalized.steps)
+    || normalized.steps < 0
+    || Object.values(normalized.usage).some((value) => !Number.isFinite(value) || value < 0)
+  ) {
+    throw new FlexHarnessValidationError('Agent generation result is invalid.');
+  }
+  return normalized;
+}
+
+function base64Size(data: string): number | undefined {
+  const compact = data.replace(/\s/g, '');
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(compact) || compact.length % 4 === 1) return undefined;
+  return Buffer.from(compact, 'base64').byteLength;
+}
+
+export function describeAttachment(
+  part: Exclude<TFlexPromptPart, { type: 'text' }>,
+): Omit<IFlexAttachmentMessagePart, 'partId' | 'type' | 'attachmentType'> {
+  let source: TFlexAttachmentSource = 'inline-base64';
+  let sizeBytes: number | undefined;
+  let inferredMediaType: string | undefined;
+  if (/^data:/i.test(part.data)) {
+    source = 'data-url';
+    const commaIndex = part.data.indexOf(',');
+    if (commaIndex >= 0) {
+      const metadata = part.data.slice(5, commaIndex);
+      const payload = part.data.slice(commaIndex + 1);
+      const metadataParts = metadata.split(';');
+      if (metadataParts[0]?.includes('/')) inferredMediaType = metadataParts[0];
+      if (metadataParts.some((entry) => entry.toLowerCase() === 'base64')) {
+        sizeBytes = base64Size(payload);
+      } else {
+        try {
+          sizeBytes = Buffer.byteLength(decodeURIComponent(payload));
+        } catch {
+          // Malformed URL encoding leaves size unknown without exposing the payload.
+        }
+      }
+    }
+  } else {
+    try {
+      const url = new URL(part.data);
+      if (url.protocol === 'http:' || url.protocol === 'https:') source = 'remote-url';
+      else sizeBytes = base64Size(part.data);
+    } catch {
+      sizeBytes = base64Size(part.data);
+    }
+  }
+  return {
+    source,
+    ...(sizeBytes === undefined ? {} : { sizeBytes }),
+    ...(part.mediaType ?? inferredMediaType
+      ? { mediaType: part.mediaType ?? inferredMediaType }
+      : {}),
+    ...(part.name ? { name: part.name } : {}),
+  };
+}
+
+export function createBoundedTransferMessage(message: IFlexMessage): IFlexMessage {
+  const projected = cloneSerializable(message);
+  requireTransferIdentifier(projected.messageId, 'messageId');
+  requireTransferIdentifier(projected.sessionId, 'sessionId');
+  requireTransferIdentifier(projected.runId, 'runId');
+  projected.createdAt = truncateUtf8(projected.createdAt, 128);
+  if (projected.completedAt !== undefined) projected.completedAt = truncateUtf8(projected.completedAt, 128);
+  if (projected.error !== undefined) projected.error = truncateUtf8(projected.error, maxTransferMetadataBytes);
+  if (projected.model) {
+    projected.model.provider = truncateUtf8(projected.model.provider, maxTransferIdentifierBytes);
+    projected.model.model = truncateUtf8(projected.model.model, maxTransferIdentifierBytes);
+    if (projected.model.displayName !== undefined) {
+      projected.model.displayName = truncateUtf8(projected.model.displayName, maxTransferMetadataBytes);
+    }
+    if (projected.model.variant !== undefined) projected.model.variant = truncateUtf8(projected.model.variant, 128);
+  }
+  for (const part of projected.parts) {
+    requireTransferIdentifier(part.partId, 'partId');
+    if (part.type === 'text' || part.type === 'reasoning') {
+      part.text = truncateUtf8(part.text, maxTransferTextBytes);
+    } else if (part.type === 'tool') {
+      part.toolCallId = truncateUtf8(part.toolCallId, maxTransferIdentifierBytes);
+      part.toolName = truncateUtf8(part.toolName, maxTransferIdentifierBytes);
+      if (part.error !== undefined) part.error = truncateUtf8(part.error, maxTransferMetadataBytes);
+    } else {
+      if (part.mediaType !== undefined) part.mediaType = truncateUtf8(part.mediaType, maxTransferIdentifierBytes);
+      if (part.name !== undefined) part.name = truncateUtf8(part.name, maxTransferMetadataBytes);
+    }
+  }
+  if (jsonBytes(projected) > maxTransferMessageBytes) {
+    projected.parts = [{
+      partId: 'transfer-elided',
+      type: 'text',
+      text: '[elided: message exceeds the transfer budget]',
+    }];
+  }
+  if (jsonBytes(projected) > maxTransferMessageBytes) {
+    throw new FlexHarnessValidationError('Stored message metadata exceeds the transfer limit.');
+  }
+  return projected;
+}