@modelprofile.com/flexharness 2.1.0 → 3.0.1

package/ts_migration/v3_legacyflexharness.ts

@@ -0,0 +1,620 @@
+import * as plugins from '../ts/plugins.js';
+import { FlexHarnessStoreFormatError, FlexHarnessValidationError } from '../ts/errors.js';
+import type {
+  IFlexHarnessStores,
+  IFlexMessage,
+  IFlexPermissionSnapshot,
+  IFlexProjectionSnapshot,
+  IFlexScopeSnapshot,
+  IFlexSession,
+  TFlexAgentModelMessage,
+  TJsonValue,
+} from '../ts/interfaces.js';
+import {
+  assertFlexPermissionSnapshot,
+  assertFlexProjectionSnapshot,
+  assertFlexScopeSnapshot,
+  assertJsonSerializable,
+  cloneSerializable,
+} from '../ts/utils.json.js';
+
+export interface IFlexLegacyStoredSessionSnapshot {
+  session: IFlexSession;
+  messages: IFlexMessage[];
+  modelHistory: TJsonValue[];
+  rememberedPermissionKeys: string[];
+}
+
+export interface IFlexLegacyHarnessSnapshot {
+  schemaVersion: 1;
+  revision: number;
+  sessions: IFlexLegacyStoredSessionSnapshot[];
+}
+
+export interface IFlexLegacyHarnessStore {
+  load(storageKey: string): Promise<IFlexLegacyHarnessSnapshot | undefined>;
+}
+
+interface ILegacyRun {
+  runId: string;
+  status: 'completed' | 'failed' | 'cancelled';
+  userMessage: IFlexMessage;
+  assistantMessage: IFlexMessage;
+}
+
+interface ILegacySessionMigrationPlan {
+  sessionId: string;
+  projectionSnapshot: IFlexProjectionSnapshot;
+  permissionSnapshot: IFlexPermissionSnapshot;
+  agentEvents: plugins.TAgentEvent[];
+}
+
+interface ILegacyMigrationPlan {
+  scopeSnapshot: IFlexScopeSnapshot;
+  sessions: ILegacySessionMigrationPlan[];
+}
+
+interface IInspectedSessionDestination {
+  plan: ILegacySessionMigrationPlan;
+  projection: IFlexProjectionSnapshot | undefined;
+  permission: IFlexPermissionSnapshot | undefined;
+  eventStore: plugins.IAgentEventStoreV2;
+  eventSnapshot: plugins.IAgentEventSnapshotV2 | undefined;
+  jobSnapshot: plugins.IToolJobSnapshot | undefined;
+}
+
+interface IMigrationProviderOwnership {
+  agentEvents: Set<string>;
+  jobs: Set<string>;
+}
+
+function requireRecord(value: unknown, path: string): 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.`);
+  }
+  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 requireNonNegativeInteger(value: unknown, path: string): void {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a non-negative integer.`);
+  }
+}
+
+function deterministicDigest(...values: unknown[]): string {
+  return plugins.crypto.createHash('sha256').update(JSON.stringify(values)).digest('hex');
+}
+
+function deterministicEventId(
+  storageKey: string,
+  sessionId: string,
+  ...coordinates: unknown[]
+): string {
+  return `legacy_${deterministicDigest(storageKey, sessionId, ...coordinates)}`;
+}
+
+function deterministicTimestamp(value: string, path: string): number {
+  if (!/(?:Z|[+-]\d{2}:\d{2})$/i.test(value)) {
+    throw new FlexHarnessStoreFormatError(`${path} must include an explicit timezone.`);
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
+    throw new FlexHarnessStoreFormatError(`${path} is invalid.`);
+  }
+  return timestamp;
+}
+
+function canonicalJson(value: unknown): string {
+  const canonicalize = (current: unknown): unknown => {
+    if (Array.isArray(current)) return current.map(canonicalize);
+    if (current && typeof current === 'object') {
+      return Object.fromEntries(
+        Object.entries(current)
+          .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+          .map(([key, entry]) => [key, canonicalize(entry)]),
+      );
+    }
+    return current;
+  };
+  return JSON.stringify(canonicalize(value));
+}
+
+function withoutRevision<TSnapshot extends { revision: number }>(
+  snapshot: TSnapshot,
+): Omit<TSnapshot, 'revision'> {
+  const { revision: _revision, ...content } = snapshot;
+  return content;
+}
+
+function assertSameContent(actual: unknown, expected: unknown, destination: string): void {
+  if (canonicalJson(actual) !== canonicalJson(expected)) {
+    throw new FlexHarnessStoreFormatError(
+      `Legacy migration destination ${destination} already contains different content.`,
+    );
+  }
+}
+
+const interruptedMessageError = 'The process stopped before this message completed.';
+const interruptedToolError = 'The process stopped before this tool call completed.';
+
+function repairLegacyInterruptedSession(
+  stored: IFlexLegacyStoredSessionSnapshot,
+  path: string,
+): void {
+  const timestampValues = [
+    stored.session.createdAt,
+    stored.session.updatedAt,
+    stored.session.archivedAt,
+    ...stored.messages.flatMap((message) => [message.createdAt, message.completedAt]),
+  ].flatMap((value) => value === undefined ? [] : [value]);
+  const recoveredAt = new Date(Math.max(...timestampValues.map((value, index) => (
+    deterministicTimestamp(value, `${path}.recoveryTimestamps[${index}]`)
+  )))).toISOString();
+  if (
+    stored.session.status === 'running'
+    || stored.session.status === 'waiting_permission'
+  ) {
+    stored.session.status = 'idle';
+    stored.session.activity = { status: 'idle' };
+    stored.session.updatedAt = recoveredAt;
+  } else if (
+    stored.session.activity.status === 'running'
+    || stored.session.activity.status === 'waiting_permission'
+  ) {
+    stored.session.activity = { status: 'idle' };
+    stored.session.updatedAt = recoveredAt;
+  }
+  for (const message of stored.messages) {
+    if (message.status === 'streaming') {
+      message.status = 'cancelled';
+      message.completedAt = recoveredAt;
+      message.error = interruptedMessageError;
+    }
+    for (const part of message.parts) {
+      if (part.type === 'reasoning' && part.status === 'running') {
+        part.status = 'cancelled';
+      }
+      if (part.type === 'tool' && part.status === 'running') {
+        part.status = 'cancelled';
+        part.error = interruptedToolError;
+      }
+    }
+  }
+}
+
+function groupLegacyRuns(
+  messages: readonly IFlexMessage[],
+  sessionId: string,
+  path: string,
+): ILegacyRun[] {
+  const groups = new Map<string, Array<{ message: IFlexMessage; index: number; timestamp: number }>>();
+  let priorTimestamp = -1;
+  for (const [index, message] of messages.entries()) {
+    const messagePath = `${path}[${index}]`;
+    if (message.sessionId !== sessionId) {
+      throw new FlexHarnessStoreFormatError(`${messagePath}.sessionId does not match its session.`);
+    }
+    const timestamp = deterministicTimestamp(message.createdAt, `${messagePath}.createdAt`);
+    if (timestamp < priorTimestamp) {
+      throw new FlexHarnessStoreFormatError(`${path} must be in chronological order.`);
+    }
+    priorTimestamp = timestamp;
+    const group = groups.get(message.runId) ?? [];
+    group.push({ message, index, timestamp });
+    groups.set(message.runId, group);
+  }
+
+  const runs: ILegacyRun[] = [];
+  let expectedIndex = 0;
+  for (const [runId, group] of groups) {
+    if (group.length !== 2) {
+      throw new FlexHarnessStoreFormatError(
+        `${path} run "${runId}" must contain exactly one user and one assistant message.`,
+      );
+    }
+    const [user, assistant] = group;
+    if (user.index !== expectedIndex || assistant.index !== expectedIndex + 1) {
+      throw new FlexHarnessStoreFormatError(`${path} contains ambiguous interleaved run groups.`);
+    }
+    expectedIndex += 2;
+    if (user.message.role !== 'user' || assistant.message.role !== 'assistant') {
+      throw new FlexHarnessStoreFormatError(
+        `${path} run "${runId}" must contain a user message followed by an assistant message.`,
+      );
+    }
+    if (user.message.runId !== runId || assistant.message.runId !== runId) {
+      throw new FlexHarnessStoreFormatError(`${path} run "${runId}" has mismatched run IDs.`);
+    }
+    if (user.timestamp > assistant.timestamp) {
+      throw new FlexHarnessStoreFormatError(`${path} run "${runId}" is not chronological.`);
+    }
+    if (user.message.status === 'streaming' || assistant.message.status === 'streaming') {
+      throw new FlexHarnessStoreFormatError(`${path} run "${runId}" is not terminal.`);
+    }
+    if (user.message.status !== assistant.message.status) {
+      throw new FlexHarnessStoreFormatError(`${path} run "${runId}" has mismatched statuses.`);
+    }
+    runs.push({
+      runId,
+      status: user.message.status,
+      userMessage: user.message,
+      assistantMessage: assistant.message,
+    });
+  }
+  return runs;
+}
+
+function generationOutcome(status: ILegacyRun['status']): plugins.TAgentGenerationOutcome {
+  if (status === 'completed') return 'accepted';
+  if (status === 'failed') return 'rejected';
+  return 'interrupted';
+}
+
+function createSessionAgentEvents(
+  storageKey: string,
+  stored: IFlexLegacyStoredSessionSnapshot,
+  runs: readonly ILegacyRun[],
+  path: string,
+): plugins.TAgentEvent[] {
+  const { sessionId } = stored.session;
+  const baseTimestamp = deterministicTimestamp(stored.session.createdAt, `${path}.session.createdAt`);
+  let sequence = 0;
+  const nextIdentity = () => {
+    sequence++;
+    const timestamp = baseTimestamp + sequence - 1;
+    if (!Number.isSafeInteger(timestamp)) {
+      throw new FlexHarnessStoreFormatError(
+        `${path} contains too many events for its createdAt timestamp.`,
+      );
+    }
+    return { sequence, timestamp };
+  };
+  const converted = plugins.modelMessagesToAgentEvents(
+    stored.modelHistory as unknown as TFlexAgentModelMessage[],
+    {
+      identityFactory: (coordinates) => deterministicEventId(
+        storageKey,
+        sessionId,
+        'model-history',
+        coordinates.messageIndex,
+        coordinates.partIndex ?? null,
+        coordinates.eventKind,
+      ),
+    },
+  );
+  const events: plugins.TAgentEvent[] = converted.map((event) => ({
+    ...event,
+    ...nextIdentity(),
+  }));
+
+  for (const run of runs) {
+    const begun = plugins.createAgentEvent<plugins.IGenerationBegunEvent>({
+      type: 'generation-begun',
+      id: deterministicEventId(storageKey, sessionId, 'run', run.runId, 'begun'),
+      ...nextIdentity(),
+      generationId: run.runId,
+      claimTokenDigest: deterministicDigest(storageKey, sessionId, run.runId, 'claim-token'),
+      ...(events.length > 0 ? { parentIds: [events[events.length - 1].id] } : {}),
+    });
+    const started = plugins.createAgentEvent<plugins.IGenerationExecutionStartedEvent>({
+      type: 'generation-execution-started',
+      id: deterministicEventId(storageKey, sessionId, 'run', run.runId, 'execution-started'),
+      ...nextIdentity(),
+      generationId: run.runId,
+      parentIds: [begun.id],
+    });
+    const completed = plugins.createAgentEvent<plugins.IGenerationExecutionCompletedEvent>({
+      type: 'generation-execution-completed',
+      id: deterministicEventId(storageKey, sessionId, 'run', run.runId, 'execution-completed'),
+      ...nextIdentity(),
+      generationId: run.runId,
+      parentIds: [started.id],
+    });
+    const outcome = plugins.createAgentEvent<plugins.IGenerationOutcomeEvent>({
+      type: 'generation-outcome',
+      id: deterministicEventId(storageKey, sessionId, 'run', run.runId, 'outcome'),
+      ...nextIdentity(),
+      generationId: run.runId,
+      outcome: generationOutcome(run.status),
+      parentIds: [completed.id],
+    });
+    events.push(begun, started, completed, outcome);
+  }
+
+  const jsonEvents = JSON.parse(JSON.stringify(events)) as plugins.TAgentEvent[];
+  try {
+    plugins.validateAgentEventSnapshotV2({
+      schemaVersion: 2,
+      sessionId,
+      revision: 1,
+      updatedAt: baseTimestamp,
+      events: jsonEvents,
+    }, sessionId);
+  } catch (error) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.modelHistory cannot be converted to valid canonical Agent events: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  const transactions = plugins.getAgentGenerationTransactions(jsonEvents);
+  if (transactions.size !== runs.length) {
+    throw new FlexHarnessStoreFormatError(`${path}.messages do not produce unambiguous transactions.`);
+  }
+  for (const run of runs) {
+    if (transactions.get(run.runId)?.state !== generationOutcome(run.status)) {
+      throw new FlexHarnessStoreFormatError(
+        `${path}.messages run "${run.runId}" produces an invalid transaction lifecycle.`,
+      );
+    }
+  }
+  return jsonEvents;
+}
+
+function createMigrationPlan(
+  storageKey: string,
+  legacySnapshot: IFlexLegacyHarnessSnapshot,
+): ILegacyMigrationPlan {
+  if (typeof storageKey !== 'string' || !storageKey.trim()) {
+    throw new FlexHarnessValidationError('storageKey must be a non-empty string.');
+  }
+  assertJsonSerializable(legacySnapshot, '$legacySnapshot');
+  const snapshot = requireRecord(legacySnapshot, '$legacySnapshot');
+  requireOnlyKeys(snapshot, ['schemaVersion', 'revision', 'sessions'], '$legacySnapshot');
+  if (snapshot.schemaVersion !== 1) {
+    throw new FlexHarnessStoreFormatError('Legacy snapshot schemaVersion must be 1.');
+  }
+  requireNonNegativeInteger(snapshot.revision, '$legacySnapshot.revision');
+  if (!Array.isArray(snapshot.sessions)) {
+    throw new FlexHarnessStoreFormatError('$legacySnapshot.sessions must be an array.');
+  }
+
+  const legacy = cloneSerializable(legacySnapshot);
+  const sessionIds = new Set<string>();
+  const eventIds = new Set<string>();
+  const sessions = legacy.sessions.map((stored, index): ILegacySessionMigrationPlan => {
+    const path = `$legacySnapshot.sessions[${index}]`;
+    const storedRecord = requireRecord(stored, path);
+    requireOnlyKeys(
+      storedRecord,
+      ['session', 'messages', 'modelHistory', 'rememberedPermissionKeys'],
+      path,
+    );
+    const scopeSnapshot: IFlexScopeSnapshot = {
+      schemaVersion: 1,
+      revision: 1,
+      sessions: [stored.session],
+      tombstones: [],
+    };
+    const projectionSnapshot: IFlexProjectionSnapshot = {
+      schemaVersion: 1,
+      revision: 1,
+      messages: stored.messages,
+      stagedTerminals: [],
+    };
+    const permissionSnapshot: IFlexPermissionSnapshot = {
+      schemaVersion: 1,
+      revision: 1,
+      rememberedPermissionKeys: stored.rememberedPermissionKeys,
+    };
+    assertFlexScopeSnapshot(scopeSnapshot);
+    assertFlexProjectionSnapshot(projectionSnapshot);
+    assertFlexPermissionSnapshot(permissionSnapshot);
+    repairLegacyInterruptedSession(stored, path);
+    assertFlexScopeSnapshot(scopeSnapshot);
+    assertFlexProjectionSnapshot(projectionSnapshot);
+    const { sessionId } = stored.session;
+    if (sessionIds.has(sessionId)) {
+      throw new FlexHarnessStoreFormatError(
+        `$legacySnapshot contains duplicate session "${sessionId}".`,
+      );
+    }
+    sessionIds.add(sessionId);
+    const runs = groupLegacyRuns(stored.messages, sessionId, `${path}.messages`);
+    const agentEvents = createSessionAgentEvents(storageKey, stored, runs, path);
+    for (const event of agentEvents) {
+      if (eventIds.has(event.id)) {
+        throw new FlexHarnessStoreFormatError(
+          `$legacySnapshot produces duplicate Agent event ID "${event.id}".`,
+        );
+      }
+      eventIds.add(event.id);
+    }
+    return {
+      sessionId,
+      projectionSnapshot: cloneSerializable(projectionSnapshot),
+      permissionSnapshot: cloneSerializable(permissionSnapshot),
+      agentEvents,
+    };
+  });
+  const scopeSnapshot: IFlexScopeSnapshot = {
+    schemaVersion: 1,
+    revision: 1,
+    sessions: legacy.sessions.map((stored) => cloneSerializable(stored.session)),
+    tombstones: [],
+  };
+  assertFlexScopeSnapshot(scopeSnapshot);
+  return { scopeSnapshot, sessions };
+}
+
+function assertCompatibleJobSnapshot(
+  snapshot: plugins.IToolJobSnapshot | undefined,
+  sessionId: string,
+): void {
+  if (!snapshot) return;
+  if (
+    snapshot.schemaVersion !== 1
+    || !Number.isSafeInteger(snapshot.revision)
+    || snapshot.revision < 0
+    || !Number.isSafeInteger(snapshot.updatedAt)
+    || snapshot.updatedAt < 0
+    || !Array.isArray(snapshot.jobs)
+    || snapshot.jobs.length > 0
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `Legacy migration destination jobs for session "${sessionId}" is not an empty job snapshot.`,
+    );
+  }
+}
+
+async function inspectDestinations(
+  storageKey: string,
+  plan: ILegacyMigrationPlan,
+  stores: IFlexHarnessStores,
+  ownership: IMigrationProviderOwnership,
+): Promise<{
+  scope: IFlexScopeSnapshot | undefined;
+  sessions: IInspectedSessionDestination[];
+}> {
+  const scope = await stores.scopes.load(storageKey);
+  const sessions: IInspectedSessionDestination[] = [];
+  for (const session of plan.sessions) {
+    const [projection, permission] = await Promise.all([
+      stores.projections.load(storageKey, session.sessionId),
+      stores.permissions.load(storageKey, session.sessionId),
+    ]);
+    const eventStore = await stores.agentEvents.getStore(storageKey, session.sessionId);
+    ownership.agentEvents.add(session.sessionId);
+    const jobStore = await stores.jobs.getStore(storageKey, session.sessionId);
+    ownership.jobs.add(session.sessionId);
+    const [eventSnapshot, jobSnapshot] = await Promise.all([
+      eventStore.load(session.sessionId),
+      jobStore.load(),
+    ]);
+    sessions.push({
+      plan: session,
+      projection,
+      permission,
+      eventStore,
+      eventSnapshot: eventSnapshot as plugins.IAgentEventSnapshotV2 | undefined,
+      jobSnapshot,
+    });
+  }
+
+  if (scope) {
+    assertSameContent(withoutRevision(scope), withoutRevision(plan.scopeSnapshot), 'scope snapshot');
+  }
+  for (const session of sessions) {
+    if (session.projection) {
+      assertSameContent(
+        withoutRevision(session.projection),
+        withoutRevision(session.plan.projectionSnapshot),
+        `projection snapshot for session "${session.plan.sessionId}"`,
+      );
+    }
+    if (session.permission) {
+      assertSameContent(
+        withoutRevision(session.permission),
+        withoutRevision(session.plan.permissionSnapshot),
+        `permission snapshot for session "${session.plan.sessionId}"`,
+      );
+    }
+    if (session.eventSnapshot) {
+      assertSameContent(
+        {
+          schemaVersion: session.eventSnapshot.schemaVersion,
+          sessionId: session.eventSnapshot.sessionId,
+          events: session.eventSnapshot.events,
+        },
+        {
+          schemaVersion: 2,
+          sessionId: session.plan.sessionId,
+          events: session.plan.agentEvents,
+        },
+        `Agent events for session "${session.plan.sessionId}"`,
+      );
+    }
+    assertCompatibleJobSnapshot(session.jobSnapshot, session.plan.sessionId);
+  }
+  return { scope, sessions };
+}
+
+async function releaseMigrationProviders(
+  storageKey: string,
+  stores: IFlexHarnessStores,
+  ownership: IMigrationProviderOwnership,
+): Promise<unknown[]> {
+  const releases: Promise<void>[] = [];
+  if (stores.agentEvents.releaseSession) {
+    for (const sessionId of ownership.agentEvents) {
+      releases.push(Promise.resolve().then(() =>
+        stores.agentEvents.releaseSession!(storageKey, sessionId)));
+    }
+  }
+  if (stores.jobs.releaseSession) {
+    for (const sessionId of ownership.jobs) {
+      releases.push(Promise.resolve().then(() =>
+        stores.jobs.releaseSession!(storageKey, sessionId)));
+    }
+  }
+  const results = await Promise.allSettled(releases);
+  return results
+    .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+    .map((result) => result.reason);
+}
+
+/** Migrates one stopped, exclusively owned 2.x storage namespace into the 3.x stores. */
+export async function migrateLegacyFlexHarnessSnapshot(
+  storageKey: string,
+  legacySnapshot: IFlexLegacyHarnessSnapshot,
+  stores: IFlexHarnessStores,
+): Promise<void> {
+  const plan = createMigrationPlan(storageKey, legacySnapshot);
+  const ownership: IMigrationProviderOwnership = {
+    agentEvents: new Set(),
+    jobs: new Set(),
+  };
+  let operationError: unknown;
+  try {
+    const destinations = await inspectDestinations(storageKey, plan, stores, ownership);
+
+    for (const destination of destinations.sessions) {
+      const session = destination.plan;
+      if (!destination.projection) {
+        await stores.projections.save(
+          storageKey,
+          session.sessionId,
+          session.projectionSnapshot,
+          0,
+        );
+      }
+      if (!destination.permission) {
+        await stores.permissions.save(
+          storageKey,
+          session.sessionId,
+          session.permissionSnapshot,
+          0,
+        );
+      }
+      if (!destination.eventSnapshot) {
+        await destination.eventStore.save(session.sessionId, session.agentEvents, 0);
+      }
+    }
+    if (!destinations.scope) {
+      await stores.scopes.save(storageKey, plan.scopeSnapshot, 0);
+    }
+  } catch (error) {
+    operationError = error;
+  }
+  const errors = await releaseMigrationProviders(storageKey, stores, ownership);
+  if (operationError !== undefined) errors.unshift(operationError);
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, 'Legacy FlexHarness migration failed.');
+}