@modelprofile.com/flexharness 2.1.0 → 3.0.1

package/ts/utils.json.ts

@@ -1,7 +1,9 @@
 import { FlexHarnessStoreFormatError, FlexHarnessValidationError } from './errors.js';
 import type {
-  IFlexHarnessSnapshot,
   IFlexJsonLimits,
+  IFlexPermissionSnapshot,
+  IFlexProjectionSnapshot,
+  IFlexScopeSnapshot,
   TFlexAgentModelMessage,
   TJsonValue,
 } from './interfaces.js';
@@ -370,6 +372,17 @@ function requireRecord(value: unknown, path: string): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 
+function requireOnlyKeys(
+  value: Record<string, unknown>,
+  allowedKeys: readonly string[],
+  path: string,
+): void {
+  const unexpectedKey = Object.keys(value).find((key) => !allowedKeys.includes(key));
+  if (unexpectedKey) {
+    throw new FlexHarnessStoreFormatError(`${path}.${unexpectedKey} is not supported.`);
+  }
+}
+
 function requireString(value: unknown, path: string): string {
   if (typeof value !== 'string' || value.length === 0) {
     throw new FlexHarnessStoreFormatError(`${path} must be a non-empty string.`);
@@ -387,6 +400,12 @@ function requireNonNegativeNumber(value: unknown, path: string): void {
   }
 }
 
+function requireNonNegativeInteger(value: unknown, path: string): void {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a non-negative integer.`);
+  }
+}
+
 function requireStringArray(value: unknown, path: string): string[] {
   if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
     throw new FlexHarnessStoreFormatError(`${path} must be an array of strings.`);
@@ -394,187 +413,355 @@ function requireStringArray(value: unknown, path: string): string[] {
   return value;
 }
 
-function validateSessionSnapshot(value: unknown, path: string): string {
-  const stored = requireRecord(value, path);
-  const session = requireRecord(stored.session, `${path}.session`);
-  const sessionId = requireString(session.sessionId, `${path}.session.sessionId`);
-  requireString(session.scopeId, `${path}.session.scopeId`);
-  requireString(session.createdAt, `${path}.session.createdAt`);
-  requireString(session.updatedAt, `${path}.session.updatedAt`);
-  requireOptionalString(session.title, `${path}.session.title`);
-  requireOptionalString(session.archivedAt, `${path}.session.archivedAt`);
-  if (!['idle', 'running', 'waiting_permission', 'failed', 'cancelled'].includes(String(session.status))) {
-    throw new FlexHarnessStoreFormatError(`${path}.session.status is invalid.`);
-  }
-  const activity = requireRecord(session.activity, `${path}.session.activity`);
-  if (!['idle', 'running', 'waiting_permission', 'failed', 'cancelled'].includes(String(activity.status))) {
-    throw new FlexHarnessStoreFormatError(`${path}.session.activity.status is invalid.`);
-  }
-  requireOptionalString(activity.runId, `${path}.session.activity.runId`);
-  requireOptionalString(activity.startedAt, `${path}.session.activity.startedAt`);
-  requireOptionalString(activity.completedAt, `${path}.session.activity.completedAt`);
-  requireOptionalString(activity.error, `${path}.session.activity.error`);
-
-  if (!Array.isArray(stored.messages)) {
-    throw new FlexHarnessStoreFormatError(`${path}.messages must be an array.`);
-  }
-  const messageIds = new Set<string>();
-  for (let index = 0; index < stored.messages.length; index++) {
-    const messagePath = `${path}.messages[${index}]`;
-    const message = requireRecord(stored.messages[index], messagePath);
-    const messageId = requireString(message.messageId, `${messagePath}.messageId`);
-    if (messageIds.has(messageId)) {
-      throw new FlexHarnessStoreFormatError(`${path}.messages contains duplicate message "${messageId}".`);
-    }
-    messageIds.add(messageId);
-    if (requireString(message.sessionId, `${messagePath}.sessionId`) !== sessionId) {
-      throw new FlexHarnessStoreFormatError(`${messagePath}.sessionId does not match its session.`);
-    }
-    requireString(message.runId, `${messagePath}.runId`);
-    requireString(message.createdAt, `${messagePath}.createdAt`);
-    requireOptionalString(message.completedAt, `${messagePath}.completedAt`);
-    requireOptionalString(message.error, `${messagePath}.error`);
-    if (!['user', 'assistant'].includes(String(message.role))) {
-      throw new FlexHarnessStoreFormatError(`${messagePath}.role is invalid.`);
-    }
-    if (!['streaming', 'completed', 'failed', 'cancelled'].includes(String(message.status))) {
-      throw new FlexHarnessStoreFormatError(`${messagePath}.status is invalid.`);
-    }
-    if (!Array.isArray(message.parts)) {
-      throw new FlexHarnessStoreFormatError(`${messagePath}.parts must be an array.`);
-    }
-    if (message.model !== undefined) {
-      const model = requireRecord(message.model, `${messagePath}.model`);
-      requireString(model.provider, `${messagePath}.model.provider`);
-      requireString(model.model, `${messagePath}.model.model`);
-      requireOptionalString(model.displayName, `${messagePath}.model.displayName`);
-      requireOptionalString(model.variant, `${messagePath}.model.variant`);
-    }
-    if (message.usage !== undefined) {
-      const usage = requireRecord(message.usage, `${messagePath}.usage`);
-      requireNonNegativeNumber(usage.inputTokens, `${messagePath}.usage.inputTokens`);
-      requireNonNegativeNumber(usage.outputTokens, `${messagePath}.usage.outputTokens`);
-      requireNonNegativeNumber(usage.totalTokens, `${messagePath}.usage.totalTokens`);
-      requireNonNegativeNumber(usage.cacheReadTokens, `${messagePath}.usage.cacheReadTokens`);
-      requireNonNegativeNumber(usage.cacheWriteTokens, `${messagePath}.usage.cacheWriteTokens`);
-    }
-    const partIds = new Set<string>();
-    for (let partIndex = 0; partIndex < message.parts.length; partIndex++) {
-      const partPath = `${messagePath}.parts[${partIndex}]`;
-      const part = requireRecord(message.parts[partIndex], partPath);
-      const partId = requireString(part.partId, `${partPath}.partId`);
-      if (partIds.has(partId)) {
-        throw new FlexHarnessStoreFormatError(`${messagePath}.parts contains duplicate part "${partId}".`);
+const activityStatuses = [
+  'idle',
+  'scheduled',
+  'running',
+  'waiting_permission',
+  'failed',
+  'cancelled',
+] as const;
+
+function validateSession(value: unknown, path: string): string {
+  const session = requireRecord(value, path);
+  requireOnlyKeys(
+    session,
+    [
+      'scopeId',
+      'sessionId',
+      'title',
+      'createdAt',
+      'updatedAt',
+      'archivedAt',
+      'status',
+      'activity',
+    ],
+    path,
+  );
+  requireString(session.scopeId, `${path}.scopeId`);
+  const sessionId = requireString(session.sessionId, `${path}.sessionId`);
+  requireOptionalString(session.title, `${path}.title`);
+  requireString(session.createdAt, `${path}.createdAt`);
+  requireString(session.updatedAt, `${path}.updatedAt`);
+  requireOptionalString(session.archivedAt, `${path}.archivedAt`);
+  if (!activityStatuses.includes(session.status as (typeof activityStatuses)[number])) {
+    throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
+  }
+  const activity = requireRecord(session.activity, `${path}.activity`);
+  requireOnlyKeys(activity, ['runId', 'status', 'startedAt', 'completedAt', 'error'], `${path}.activity`);
+  if (!activityStatuses.includes(activity.status as (typeof activityStatuses)[number])) {
+    throw new FlexHarnessStoreFormatError(`${path}.activity.status is invalid.`);
+  }
+  requireOptionalString(activity.runId, `${path}.activity.runId`);
+  requireOptionalString(activity.startedAt, `${path}.activity.startedAt`);
+  requireOptionalString(activity.completedAt, `${path}.activity.completedAt`);
+  requireOptionalString(activity.error, `${path}.activity.error`);
+  return sessionId;
+}
+
+function validateModel(value: unknown, path: string): void {
+  const model = requireRecord(value, path);
+  requireOnlyKeys(model, ['provider', 'model', 'displayName', 'variant'], path);
+  requireString(model.provider, `${path}.provider`);
+  requireString(model.model, `${path}.model`);
+  requireOptionalString(model.displayName, `${path}.displayName`);
+  requireOptionalString(model.variant, `${path}.variant`);
+}
+
+function validateUsage(value: unknown, path: string): void {
+  const usage = requireRecord(value, path);
+  requireOnlyKeys(
+    usage,
+    ['inputTokens', 'outputTokens', 'totalTokens', 'cacheReadTokens', 'cacheWriteTokens'],
+    path,
+  );
+  requireNonNegativeNumber(usage.inputTokens, `${path}.inputTokens`);
+  requireNonNegativeNumber(usage.outputTokens, `${path}.outputTokens`);
+  requireNonNegativeNumber(usage.totalTokens, `${path}.totalTokens`);
+  requireNonNegativeNumber(usage.cacheReadTokens, `${path}.cacheReadTokens`);
+  requireNonNegativeNumber(usage.cacheWriteTokens, `${path}.cacheWriteTokens`);
+}
+
+interface IValidatedMessageIdentity {
+  messageId: string;
+  sessionId: string;
+  runId: string;
+  role: 'user' | 'assistant';
+  status: 'streaming' | 'completed' | 'failed' | 'cancelled';
+}
+
+function validateMessage(value: unknown, path: string): IValidatedMessageIdentity {
+  const message = requireRecord(value, path);
+  requireOnlyKeys(
+    message,
+    [
+      'messageId',
+      'sessionId',
+      'runId',
+      'role',
+      'status',
+      'createdAt',
+      'completedAt',
+      'parts',
+      'model',
+      'usage',
+      'error',
+    ],
+    path,
+  );
+  const messageId = requireString(message.messageId, `${path}.messageId`);
+  const sessionId = requireString(message.sessionId, `${path}.sessionId`);
+  const runId = requireString(message.runId, `${path}.runId`);
+  if (message.role !== 'user' && message.role !== 'assistant') {
+    throw new FlexHarnessStoreFormatError(`${path}.role is invalid.`);
+  }
+  if (!['streaming', 'completed', 'failed', 'cancelled'].includes(String(message.status))) {
+    throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
+  }
+  requireString(message.createdAt, `${path}.createdAt`);
+  requireOptionalString(message.completedAt, `${path}.completedAt`);
+  requireOptionalString(message.error, `${path}.error`);
+  if (message.model !== undefined) validateModel(message.model, `${path}.model`);
+  if (message.usage !== undefined) validateUsage(message.usage, `${path}.usage`);
+  if (!Array.isArray(message.parts)) {
+    throw new FlexHarnessStoreFormatError(`${path}.parts must be an array.`);
+  }
+  const partIds = new Set<string>();
+  for (let index = 0; index < message.parts.length; index++) {
+    const partPath = `${path}.parts[${index}]`;
+    const part = requireRecord(message.parts[index], partPath);
+    const partId = requireString(part.partId, `${partPath}.partId`);
+    if (partIds.has(partId)) {
+      throw new FlexHarnessStoreFormatError(`${path}.parts contains duplicate part "${partId}".`);
+    }
+    partIds.add(partId);
+    if (part.type === 'text') {
+      requireOnlyKeys(part, ['partId', 'type', 'text'], partPath);
+      if (typeof part.text !== 'string') {
+        throw new FlexHarnessStoreFormatError(`${partPath}.text must be a string.`);
       }
-      partIds.add(partId);
-      if (!['text', 'reasoning', 'tool', 'attachment'].includes(String(part.type))) {
-        throw new FlexHarnessStoreFormatError(`${partPath}.type is invalid.`);
+    } else if (part.type === 'reasoning') {
+      requireOnlyKeys(part, ['partId', 'type', 'text', 'status'], partPath);
+      if (typeof part.text !== 'string') {
+        throw new FlexHarnessStoreFormatError(`${partPath}.text must be a string.`);
       }
-      if (part.type === 'text') {
-        if (typeof part.text !== 'string') {
-          throw new FlexHarnessStoreFormatError(`${partPath}.text must be a string.`);
-        }
-      } else if (part.type === 'reasoning') {
-        if (typeof part.text !== 'string') {
-          throw new FlexHarnessStoreFormatError(`${partPath}.text must be a string.`);
-        }
-        if (!['running', 'completed', 'cancelled'].includes(String(part.status))) {
-          throw new FlexHarnessStoreFormatError(`${partPath}.status is invalid.`);
-        }
-      } else if (part.type === 'tool') {
-        requireString(part.toolCallId, `${partPath}.toolCallId`);
-        requireString(part.toolName, `${partPath}.toolName`);
-        if (!['running', 'completed', 'failed', 'cancelled'].includes(String(part.status))) {
-          throw new FlexHarnessStoreFormatError(`${partPath}.status is invalid.`);
-        }
-        if (!Object.prototype.hasOwnProperty.call(part, 'input')) {
-          throw new FlexHarnessStoreFormatError(`${partPath}.input is required.`);
-        }
-        requireOptionalString(part.error, `${partPath}.error`);
-      } else {
-        const unsupportedAttachmentField = Object.keys(part).find(
-          (key) =>
-            ![
-              'partId',
-              'type',
-              'attachmentType',
-              'source',
-              'sizeBytes',
-              'mediaType',
-              'name',
-            ].includes(key),
-        );
-        if (unsupportedAttachmentField) {
-          throw new FlexHarnessStoreFormatError(
-            `${partPath}.${unsupportedAttachmentField} is not public attachment metadata.`,
-          );
-        }
-        if (!['image', 'file'].includes(String(part.attachmentType))) {
-          throw new FlexHarnessStoreFormatError(`${partPath}.attachmentType is invalid.`);
-        }
-        if (!['inline-base64', 'data-url', 'remote-url'].includes(String(part.source))) {
-          throw new FlexHarnessStoreFormatError(`${partPath}.source is invalid.`);
-        }
-        if (
-          part.sizeBytes !== undefined &&
-          (!Number.isSafeInteger(part.sizeBytes) || Number(part.sizeBytes) < 0)
-        ) {
-          throw new FlexHarnessStoreFormatError(
-            `${partPath}.sizeBytes must be a non-negative integer.`,
-          );
-        }
-        requireOptionalString(part.mediaType, `${partPath}.mediaType`);
-        requireOptionalString(part.name, `${partPath}.name`);
+      if (!['running', 'completed', 'cancelled'].includes(String(part.status))) {
+        throw new FlexHarnessStoreFormatError(`${partPath}.status is invalid.`);
+      }
+    } else if (part.type === 'tool') {
+      requireOnlyKeys(
+        part,
+        ['partId', 'type', 'toolCallId', 'toolName', 'status', 'input', 'output', 'error'],
+        partPath,
+      );
+      requireString(part.toolCallId, `${partPath}.toolCallId`);
+      requireString(part.toolName, `${partPath}.toolName`);
+      if (!['running', 'completed', 'failed', 'cancelled'].includes(String(part.status))) {
+        throw new FlexHarnessStoreFormatError(`${partPath}.status is invalid.`);
+      }
+      if (!Object.prototype.hasOwnProperty.call(part, 'input')) {
+        throw new FlexHarnessStoreFormatError(`${partPath}.input is required.`);
+      }
+      requireOptionalString(part.error, `${partPath}.error`);
+    } else if (part.type === 'attachment') {
+      requireOnlyKeys(
+        part,
+        ['partId', 'type', 'attachmentType', 'source', 'sizeBytes', 'mediaType', 'name'],
+        partPath,
+      );
+      if (!['image', 'file'].includes(String(part.attachmentType))) {
+        throw new FlexHarnessStoreFormatError(`${partPath}.attachmentType is invalid.`);
       }
+      if (!['inline-base64', 'data-url', 'remote-url'].includes(String(part.source))) {
+        throw new FlexHarnessStoreFormatError(`${partPath}.source is invalid.`);
+      }
+      if (part.sizeBytes !== undefined) {
+        requireNonNegativeInteger(part.sizeBytes, `${partPath}.sizeBytes`);
+      }
+      requireOptionalString(part.mediaType, `${partPath}.mediaType`);
+      requireOptionalString(part.name, `${partPath}.name`);
+    } else {
+      throw new FlexHarnessStoreFormatError(`${partPath}.type is invalid.`);
     }
   }
+  return {
+    messageId,
+    sessionId,
+    runId,
+    role: message.role,
+    status: message.status as IValidatedMessageIdentity['status'],
+  };
+}
 
-  if (!Array.isArray(stored.modelHistory)) {
-    throw new FlexHarnessStoreFormatError(`${path}.modelHistory must be an array.`);
-  }
-  for (let index = 0; index < stored.modelHistory.length; index++) {
-    const historyPath = `${path}.modelHistory[${index}]`;
-    const message = requireRecord(stored.modelHistory[index], historyPath);
-    if (!['system', 'user', 'assistant', 'tool'].includes(String(message.role))) {
-      throw new FlexHarnessStoreFormatError(`${historyPath}.role is invalid.`);
+function validateMessages(
+  value: unknown,
+  path: string,
+  expectedSessionId?: string,
+): IValidatedMessageIdentity[] {
+  if (!Array.isArray(value)) {
+    throw new FlexHarnessStoreFormatError(`${path} must be an array.`);
+  }
+  const identities = value.map((message, index) => validateMessage(message, `${path}[${index}]`));
+  const messageIds = new Set<string>();
+  for (const identity of identities) {
+    if (messageIds.has(identity.messageId)) {
+      throw new FlexHarnessStoreFormatError(`${path} contains duplicate message "${identity.messageId}".`);
     }
-    if (typeof message.content !== 'string' && !Array.isArray(message.content)) {
-      throw new FlexHarnessStoreFormatError(`${historyPath}.content is invalid.`);
+    messageIds.add(identity.messageId);
+    if (expectedSessionId !== undefined && identity.sessionId !== expectedSessionId) {
+      throw new FlexHarnessStoreFormatError(`${path} contains a message for another session.`);
     }
   }
-  const rememberedPermissionKeys = requireStringArray(
-    stored.rememberedPermissionKeys,
-    `${path}.rememberedPermissionKeys`,
-  );
-  if (rememberedPermissionKeys.some((key) => key.length === 0)) {
-    throw new FlexHarnessStoreFormatError(`${path}.rememberedPermissionKeys contains an empty key.`);
+  return identities;
+}
+
+function validatePermissionKeys(value: unknown, path: string): void {
+  const keys = requireStringArray(value, path);
+  if (keys.some((key) => key.length === 0)) {
+    throw new FlexHarnessStoreFormatError(`${path} contains an empty key.`);
   }
-  if (new Set(rememberedPermissionKeys).size !== rememberedPermissionKeys.length) {
-    throw new FlexHarnessStoreFormatError(`${path}.rememberedPermissionKeys contains duplicate keys.`);
+  if (new Set(keys).size !== keys.length) {
+    throw new FlexHarnessStoreFormatError(`${path} contains duplicate keys.`);
   }
-  return sessionId;
 }
 
-export function assertFlexHarnessSnapshot(value: unknown): asserts value is IFlexHarnessSnapshot {
+function validateSnapshotHeader(
+  value: unknown,
+  allowedKeys: readonly string[],
+): Record<string, unknown> {
   assertJsonSerializable(value, '$snapshot');
   const snapshot = requireRecord(value, '$snapshot');
+  requireOnlyKeys(snapshot, allowedKeys, '$snapshot');
   if (snapshot.schemaVersion !== 1) {
     throw new FlexHarnessStoreFormatError('Snapshot schemaVersion must be 1.');
   }
-  if (!Number.isSafeInteger(snapshot.revision) || Number(snapshot.revision) < 0) {
-    throw new FlexHarnessStoreFormatError('Snapshot revision must be a non-negative integer.');
-  }
+  requireNonNegativeInteger(snapshot.revision, 'Snapshot revision');
+  return snapshot;
+}
+
+export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexScopeSnapshot {
+  const snapshot = validateSnapshotHeader(value, [
+    'schemaVersion',
+    'revision',
+    'sessions',
+    'tombstones',
+  ]);
   if (!Array.isArray(snapshot.sessions)) {
     throw new FlexHarnessStoreFormatError('Snapshot sessions must be an array.');
   }
   const sessionIds = new Set<string>();
   for (let index = 0; index < snapshot.sessions.length; index++) {
-    const sessionId = validateSessionSnapshot(snapshot.sessions[index], `$snapshot.sessions[${index}]`);
+    const sessionId = validateSession(snapshot.sessions[index], `$snapshot.sessions[${index}]`);
     if (sessionIds.has(sessionId)) {
       throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate session "${sessionId}".`);
     }
     sessionIds.add(sessionId);
   }
+  if (!Array.isArray(snapshot.tombstones)) {
+    throw new FlexHarnessStoreFormatError('Snapshot tombstones must be an array.');
+  }
+  const tombstoneIds = new Set<string>();
+  for (let index = 0; index < snapshot.tombstones.length; index++) {
+    const path = `$snapshot.tombstones[${index}]`;
+    const tombstone = requireRecord(snapshot.tombstones[index], path);
+    requireOnlyKeys(tombstone, ['sessionId', 'deletedAt'], path);
+    const sessionId = requireString(tombstone.sessionId, `${path}.sessionId`);
+    requireString(tombstone.deletedAt, `${path}.deletedAt`);
+    if (tombstoneIds.has(sessionId)) {
+      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate tombstone "${sessionId}".`);
+    }
+    if (sessionIds.has(sessionId)) {
+      throw new FlexHarnessStoreFormatError(
+        `Snapshot session "${sessionId}" cannot also have a tombstone.`,
+      );
+    }
+    tombstoneIds.add(sessionId);
+  }
+}
+
+export function assertFlexProjectionSnapshot(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshot {
+  const snapshot = validateSnapshotHeader(value, [
+    'schemaVersion',
+    'revision',
+    'messages',
+    'stagedTerminals',
+  ]);
+  const visibleMessages = validateMessages(snapshot.messages, '$snapshot.messages');
+  let projectionSessionId = visibleMessages[0]?.sessionId;
+  if (visibleMessages.some((message) => message.sessionId !== projectionSessionId)) {
+    throw new FlexHarnessStoreFormatError('Snapshot messages must belong to one session.');
+  }
+  if (!Array.isArray(snapshot.stagedTerminals)) {
+    throw new FlexHarnessStoreFormatError('Snapshot stagedTerminals must be an array.');
+  }
+  const runIds = new Set<string>();
+  const stagedMessageIds = new Set<string>();
+  for (let index = 0; index < snapshot.stagedTerminals.length; index++) {
+    const path = `$snapshot.stagedTerminals[${index}]`;
+    const terminal = requireRecord(snapshot.stagedTerminals[index], path);
+    requireOnlyKeys(
+      terminal,
+      [
+        'runId',
+        'status',
+        'userMessage',
+        'assistantMessage',
+        'model',
+        'usage',
+        'finishReason',
+        'steps',
+      ],
+      path,
+    );
+    const runId = requireString(terminal.runId, `${path}.runId`);
+    if (runIds.has(runId)) {
+      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate staged run "${runId}".`);
+    }
+    runIds.add(runId);
+    if (!['completed', 'failed', 'cancelled'].includes(String(terminal.status))) {
+      throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
+    }
+    const user = validateMessage(terminal.userMessage, `${path}.userMessage`);
+    const assistant = validateMessage(terminal.assistantMessage, `${path}.assistantMessage`);
+    if (user.role !== 'user' || assistant.role !== 'assistant') {
+      throw new FlexHarnessStoreFormatError(`${path} has invalid terminal message roles.`);
+    }
+    if (user.runId !== runId || assistant.runId !== runId || user.sessionId !== assistant.sessionId) {
+      throw new FlexHarnessStoreFormatError(`${path} has uncorrelated terminal messages.`);
+    }
+    if (assistant.status !== terminal.status) {
+      throw new FlexHarnessStoreFormatError(`${path}.status does not match its assistant message.`);
+    }
+    projectionSessionId ??= user.sessionId;
+    if (user.sessionId !== projectionSessionId) {
+      throw new FlexHarnessStoreFormatError(`${path} belongs to another session.`);
+    }
+    for (const messageId of [user.messageId, assistant.messageId]) {
+      if (stagedMessageIds.has(messageId)) {
+        throw new FlexHarnessStoreFormatError(
+          `Snapshot staged terminals contain duplicate message "${messageId}".`,
+        );
+      }
+      stagedMessageIds.add(messageId);
+    }
+    if (terminal.model !== undefined) validateModel(terminal.model, `${path}.model`);
+    if (terminal.usage !== undefined) validateUsage(terminal.usage, `${path}.usage`);
+    requireOptionalString(terminal.finishReason, `${path}.finishReason`);
+    if (terminal.steps !== undefined) requireNonNegativeInteger(terminal.steps, `${path}.steps`);
+  }
+}
+
+export function assertFlexPermissionSnapshot(
+  value: unknown,
+): asserts value is IFlexPermissionSnapshot {
+  const snapshot = validateSnapshotHeader(value, [
+    'schemaVersion',
+    'revision',
+    'rememberedPermissionKeys',
+  ]);
+  validatePermissionKeys(snapshot.rememberedPermissionKeys, '$snapshot.rememberedPermissionKeys');
 }
 
 export function cloneSerializable<T>(value: T): T {

package/ts/utils.prompt.ts

@@ -7,11 +7,13 @@ import type {
   TFlexPrompt,
   TFlexPromptPart,
 } from './interfaces.js';
-import { cloneSerializable } from './utils.json.js';
-import { assertJsonSerializable } from './utils.json.js';
+import {
+  assertJsonSerializable,
+  cloneSerializable,
+  serializeAgentMessages,
+} from './utils.json.js';
 
 export interface INormalizedFlexPrompt {
-  agentPrompt: TFlexAgentPrompt;
   modelMessage: TFlexAgentModelMessage;
   parts: TFlexPromptPart[];
 }
@@ -99,27 +101,6 @@ function rejectUnknownKeys(
   }
 }
 
-function toAgentParts(parts: TFlexPromptPart[]): TFlexAgentPrompt {
-  return parts.map((part) => {
-    if (part.type === 'text') {
-      return { type: 'text' as const, text: part.text };
-    }
-    if (part.type === 'image') {
-      return {
-        type: 'image' as const,
-        image: toAgentData(part.data),
-        ...(part.mediaType ? { mediaType: part.mediaType } : {}),
-      };
-    }
-    return {
-      type: 'file' as const,
-      data: toAgentData(part.data),
-      mediaType: part.mediaType,
-      ...(part.name ? { filename: part.name } : {}),
-    };
-  }) as TFlexAgentPrompt;
-}
-
 function toStoredModelParts(parts: TFlexPromptPart[]): TFlexAgentPrompt {
   return parts.map((part) => {
     if (part.type === 'text') {
@@ -154,7 +135,6 @@ export function normalizeFlexPrompt(prompt: TFlexPrompt): INormalizedFlexPrompt
       throw new FlexHarnessValidationError('prompt must not be empty.');
     }
     return {
-      agentPrompt: prompt,
       modelMessage: { role: 'user', content: prompt },
       parts: [{ type: 'text', text: prompt }],
     };
@@ -164,7 +144,6 @@ export function normalizeFlexPrompt(prompt: TFlexPrompt): INormalizedFlexPrompt
   }
   const parts = prompt.map(validatePart);
   return {
-    agentPrompt: toAgentParts(parts),
     modelMessage: {
       role: 'user',
       content: toStoredModelParts(parts),
@@ -176,7 +155,7 @@ export function normalizeFlexPrompt(prompt: TFlexPrompt): INormalizedFlexPrompt
 export function hydrateAgentMessages(
   messages: TFlexAgentModelMessage[],
 ): TFlexAgentModelMessage[] {
-  const hydrated = cloneSerializable(messages);
+  const hydrated = serializeAgentMessages(messages);
   for (const message of hydrated) {
     if (!Array.isArray(message.content)) {
       continue;

package/ts_migration/index.ts

@@ -0,0 +1 @@
+export * from './v3_legacyflexharness.js';