@modelprofile.com/flexharness 10.24.0 → 11.0.0

package/ts/classes.flexharness.imports.ts

@@ -0,0 +1,414 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessNotFoundError,
+  FlexHarnessQueueFullError,
+  FlexHarnessSessionBusyError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import {
+  FLEX_SESSION_IMPORT_MAX_DEPTH,
+  type IFlexBeginSessionImportOptions,
+  type IFlexImportedRun,
+  type IFlexSession,
+  type IFlexSessionImportHandle,
+  type IFlexSessionImportProgress,
+  type IFlexSessionOrigin,
+  type TFlexBeginSessionImportResult,
+} from './interfaces.js';
+import { cloneSerializable } from './utils.json.js';
+import { publicSnapshot } from './utils.transfer.js';
+import {
+  normalizeBeginSessionImportOptions,
+  normalizeImportedRunPage,
+  sessionImportIdentity,
+  validateSessionImportHandle,
+  type INormalizedSessionImportOptions,
+} from './utils.sessionimport.js';
+import { createSessionMetricsState } from './utils.sessionmetrics.js';
+import type {
+  IStoredSessionState,
+  IStagedSessionImport,
+  IStorageState,
+} from './interfaces.flexharness.js';
+import {
+  createSessionGenerationId,
+  requireSessionGeneration,
+  combineErrors,
+} from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** Staged imports of finished conversations as read-only sessions. */
+export class FlexHarnessSessionImports<TScope> {
+  private readonly stagedSessionImports = new Map<string, IStagedSessionImport>();
+
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async beginSessionImport(
+    scopeId: string,
+    options: IFlexBeginSessionImportOptions,
+  ): Promise<TFlexBeginSessionImportResult> {
+    this.core.assertOpen();
+    const normalized = normalizeBeginSessionImportOptions(options);
+    const { scope, state } = await this.core.resolveState(scopeId);
+    await state.scopeQueue;
+    this.core.assertOpen();
+    this.core.assertStateAcceptingWork(state);
+    const { sessionId } = normalized;
+    const identity = sessionImportIdentity(normalized.origin);
+    for (const staged of state.sessionImports.values()) {
+      if (staged.sessionId === sessionId || staged.identity === identity) {
+        throw new FlexHarnessSessionBusyError(staged.sessionId, 'is already being imported');
+      }
+    }
+    for (const stored of state.sessions.values()) {
+      const origin = stored.session.origin;
+      if (origin === undefined || sessionImportIdentity(origin) !== identity) continue;
+      const existing: TFlexBeginSessionImportResult = {
+        status: origin.digest === normalized.origin.digest ? 'already_imported' : 'digest_mismatch',
+        session: stored.session,
+      };
+      return publicSnapshot(existing);
+    }
+    if (
+      state.sessions.has(sessionId)
+      || state.tombstones.has(sessionId)
+      || state.initializingSessions.has(sessionId)
+    ) {
+      throw new FlexHarnessValidationError(`Session "${sessionId}" already exists or is being deleted.`);
+    }
+    if (normalized.parent) this.requireImportParent(state, sessionId, normalized.parent);
+    if (this.stagedSessionImports.size >= this.core.sessionImportLimits.maxOpenImports) {
+      throw new FlexHarnessQueueFullError('FlexHarness has reached its open session import limit.');
+    }
+    const staged: IStagedSessionImport = {
+      importId: `import_${plugins.crypto.randomUUID()}`,
+      scopeId,
+      state,
+      scope: scope.scope,
+      sessionId,
+      options: normalized,
+      identity,
+      runs: [],
+      runIds: new Set(),
+      messageIds: new Set(),
+      messageCount: 0,
+      bytes: 0,
+      phase: 'staging',
+    };
+    this.stagedSessionImports.set(staged.importId, staged);
+    this.armStagedImportIdleTimer(staged);
+    state.sessionImports.set(sessionId, staged);
+    state.initializingSessions.add(sessionId);
+    const started: TFlexBeginSessionImportResult = {
+      status: 'started',
+      handle: { importId: staged.importId, scopeId, sessionId },
+    };
+    return publicSnapshot(started);
+  }
+
+  public async appendImportedRuns(
+    handle: IFlexSessionImportHandle,
+    runs: readonly IFlexImportedRun[],
+  ): Promise<IFlexSessionImportProgress> {
+    const staged = this.requireStagedSessionImport(handle);
+    this.core.assertOpen();
+    this.core.assertStateAcceptingWork(staged.state);
+    const page = normalizeImportedRunPage(runs, staged.sessionId, this.core.sessionImportLimits.maxPageBytes);
+    const runIds = new Set<string>();
+    const messageIds = new Set<string>();
+    for (const run of page.runs) {
+      if (staged.runIds.has(run.user.runId) || runIds.has(run.user.runId)) {
+        throw new FlexHarnessValidationError(`Imported run "${run.user.runId}" is not unique.`);
+      }
+      runIds.add(run.user.runId);
+      for (const message of [run.user, run.assistant]) {
+        if (staged.messageIds.has(message.messageId) || messageIds.has(message.messageId)) {
+          throw new FlexHarnessValidationError(`Imported message "${message.messageId}" is not unique.`);
+        }
+        messageIds.add(message.messageId);
+      }
+    }
+    const messageCount = staged.messageCount + page.runs.length * 2;
+    if (messageCount > this.core.sessionImportLimits.maxMessagesPerSession) {
+      throw new FlexHarnessValidationError(
+        `An imported session holds at most ${this.core.sessionImportLimits.maxMessagesPerSession} messages.`,
+      );
+    }
+    const bytes = staged.bytes + page.bytes;
+    if (bytes > this.core.sessionImportLimits.maxSessionBytes) {
+      throw new FlexHarnessValidationError(
+        `An imported session holds at most ${this.core.sessionImportLimits.maxSessionBytes} message bytes.`,
+      );
+    }
+    staged.runs.push(...page.runs);
+    for (const runId of runIds) staged.runIds.add(runId);
+    for (const messageId of messageIds) staged.messageIds.add(messageId);
+    staged.messageCount = messageCount;
+    staged.bytes = bytes;
+    this.armStagedImportIdleTimer(staged);
+    return publicSnapshot({ runs: staged.runs.length, messages: messageCount, bytes });
+  }
+
+  public async commitSessionImport(handle: IFlexSessionImportHandle): Promise<IFlexSession> {
+    const staged = this.requireStagedSessionImport(handle);
+    this.core.assertOpen();
+    const { state, scopeId, sessionId, options } = staged;
+    this.core.assertStateAcceptingWork(state);
+    if (staged.runs.length === 0) {
+      throw new FlexHarnessValidationError('A session import needs at least one run before it is committed.');
+    }
+    staged.phase = 'committing';
+    this.clearStagedImportIdleTimer(staged);
+    const scope = staged.scope as TScope;
+    let resolveInitialization!: () => void;
+    const initialization = new Promise<void>((resolve) => {
+      resolveInitialization = resolve;
+    });
+    let initializationCompleted = false;
+    const completeInitialization = () => {
+      if (initializationCompleted) return;
+      initializationCompleted = true;
+      if (state.sessionInitializations.get(sessionId) === initialization) {
+        state.sessionInitializations.delete(sessionId);
+      }
+      resolveInitialization();
+    };
+    state.sessionInitializations.set(sessionId, initialization);
+    const importedAt = new Date().toISOString();
+    const origin: IFlexSessionOrigin = {
+      kind: 'import',
+      ...cloneSerializable(options.origin),
+      importedAt,
+    };
+    let metadata!: IFlexSession;
+    let reserved = false;
+    let loaded: IStoredSessionState | undefined;
+    try {
+      // A tombstone reserves the id while the projection is written, so a crash before the session
+      // is published leaves only data that the next load or deletion cleans up.
+      await this.core.mutateScope(state, () => {
+        if (state.sessions.has(sessionId) || state.tombstones.has(sessionId)) {
+          throw this.core.trustInternalError(new FlexHarnessValidationError(
+            `Session "${sessionId}" already exists or is being deleted.`,
+          ));
+        }
+        const parent = options.parent
+          ? this.requireImportParent(state, sessionId, options.parent)
+          : undefined;
+        metadata = {
+          scopeId,
+          sessionId,
+          sessionGenerationId: createSessionGenerationId(),
+          sessionGenerationSequence: state.revision + 1,
+          ...(parent?.session.configurationRef === undefined
+            ? {}
+            : { configurationRef: parent.session.configurationRef }),
+          ...(options.title === undefined ? {} : { title: options.title }),
+          createdAt: options.createdAt,
+          updatedAt: options.updatedAt,
+          archivedAt: importedAt,
+          status: 'idle',
+          activity: { status: 'idle' },
+          ...(options.parent === undefined
+            ? {}
+            : {
+                parentSessionId: options.parent.sessionId,
+                parentRunId: options.parent.runId,
+                parentToolCallId: options.parent.toolCallId,
+                agent: options.parent.agent,
+              }),
+          depth: parent === undefined ? 0 : (parent.session.depth ?? 0) + 1,
+          origin,
+        };
+        state.tombstones.set(sessionId, {
+          sessionId,
+          ...requireSessionGeneration(metadata),
+          deletedAt: importedAt,
+          rootSessionId: sessionId,
+          depth: 0,
+          imported: true,
+        });
+      });
+      reserved = true;
+      await this.core.stores.projections.save(state.storageKey, sessionId, {
+        schemaVersion: 3,
+        revision: 1,
+        metrics: createSessionMetricsState(false),
+        messages: staged.runs.flatMap((run) => [run.user, run.assistant]),
+        stagedTerminals: [],
+        reversionSegments: [],
+        revertCursor: 0,
+        excludedRunIds: [],
+        pendingReversionReleases: [],
+      }, 0);
+      const runtime = await this.core.loadSessionRuntime(state, metadata, scopeId, scope);
+      loaded = runtime;
+      await this.core.mutateScope(state, () => {
+        if (
+          state.sessions.has(sessionId)
+          || state.tombstones.get(sessionId)?.sessionGenerationId !== metadata.sessionGenerationId
+        ) {
+          throw this.core.trustInternalError(new FlexHarnessAbortError(
+            'The session import lost its reservation before it was committed.',
+          ));
+        }
+        if (options.parent) this.requireImportParent(state, sessionId, options.parent);
+        state.tombstones.delete(sessionId);
+        state.sessions.set(sessionId, runtime);
+      });
+    } catch (error) {
+      const projected = this.core.projectOperationError(error, 'persistence', scopeId, sessionId, 'session-import');
+      const errors: unknown[] = [projected];
+      if (loaded && state.sessions.get(sessionId) !== loaded) {
+        try {
+          await this.core.lifecycle.closeStoredSession(loaded);
+        } catch (closeError) {
+          this.core.lifecycle.orphanedStoredSessions.add(loaded);
+          errors.push(closeError);
+        }
+      }
+      // A fenced namespace cannot tell whether its last save was persisted; its next load resolves
+      // the reservation instead: a surviving tombstone is cleaned up, a published session is kept.
+      if (reserved && state.tombstones.has(sessionId) && state.lifecycle !== 'fenced') {
+        completeInitialization();
+        try {
+          await this.core.deletion.finishTombstoneCleanup(state, sessionId, scopeId, { scopeId, scope });
+        } catch (cleanupError) {
+          errors.push(this.core.projectOperationError(
+            cleanupError,
+            'persistence',
+            scopeId,
+            sessionId,
+            'session-import-cleanup',
+          ));
+        }
+      }
+      throw combineErrors(errors);
+    } finally {
+      this.releaseStagedSessionImport(staged);
+      completeInitialization();
+    }
+    const result = publicSnapshot(metadata);
+    this.core.emitEvent(scopeId, metadata, { type: 'session.created', session: result });
+    return result;
+  }
+
+  public async abortSessionImport(handle: IFlexSessionImportHandle): Promise<void> {
+    const staged = this.findStagedSessionImport(handle);
+    if (!staged) return;
+    if (staged.phase === 'committing') {
+      throw new FlexHarnessSessionBusyError(staged.sessionId, 'is being committed');
+    }
+    this.releaseStagedSessionImport(staged);
+  }
+
+  public assertNoCommittingSessionImport(state: IStorageState, sessionId: string): void {
+    if (state.sessionImports.get(sessionId)?.phase === 'committing') {
+      throw new FlexHarnessSessionBusyError(sessionId, 'is being imported');
+    }
+  }
+
+  private findStagedSessionImport(
+    handle: IFlexSessionImportHandle,
+  ): IStagedSessionImport | undefined {
+    const validated = validateSessionImportHandle(handle);
+    const staged = this.stagedSessionImports.get(validated.importId);
+    if (
+      staged
+      && (staged.scopeId !== validated.scopeId || staged.sessionId !== validated.sessionId)
+    ) {
+      throw new FlexHarnessValidationError('The session import handle does not match its import.');
+    }
+    return staged;
+  }
+
+  private requireStagedSessionImport(handle: IFlexSessionImportHandle): IStagedSessionImport {
+    const staged = this.findStagedSessionImport(handle);
+    if (!staged) throw new FlexHarnessNotFoundError('Session import', handle.importId);
+    if (staged.phase !== 'staging') {
+      throw new FlexHarnessSessionBusyError(staged.sessionId, 'is being committed');
+    }
+    return staged;
+  }
+
+  private armStagedImportIdleTimer(staged: IStagedSessionImport): void {
+    this.clearStagedImportIdleTimer(staged);
+    const timer = setTimeout(() => {
+      if (staged.idleTimer !== timer) return;
+      delete staged.idleTimer;
+      if (staged.phase === 'staging') this.releaseStagedSessionImport(staged);
+    }, this.core.sessionImportLimits.stagedImportIdleTimeoutMs);
+    timer.unref();
+    staged.idleTimer = timer;
+  }
+
+  private clearStagedImportIdleTimer(staged: IStagedSessionImport): void {
+    if (staged.idleTimer === undefined) return;
+    clearTimeout(staged.idleTimer);
+    delete staged.idleTimer;
+  }
+
+  public releaseStagedSessionImport(staged: IStagedSessionImport): void {
+    this.clearStagedImportIdleTimer(staged);
+    if (this.stagedSessionImports.get(staged.importId) === staged) {
+      this.stagedSessionImports.delete(staged.importId);
+    }
+    if (staged.state.sessionImports.get(staged.sessionId) === staged) {
+      staged.state.sessionImports.delete(staged.sessionId);
+      staged.state.initializingSessions.delete(staged.sessionId);
+    }
+    staged.runs = [];
+    staged.runIds.clear();
+    staged.messageIds.clear();
+  }
+
+  /**
+   * An imported child session belongs to a committed imported parent whose run `parent.runId` holds
+   * the tool call `parent.toolCallId` naming the child, and no other session claims that tool call.
+   */
+  private requireImportParent(
+    state: IStorageState,
+    sessionId: string,
+    parent: NonNullable<INormalizedSessionImportOptions['parent']>,
+  ): IStoredSessionState {
+    const parentStored = state.initializingSessions.has(parent.sessionId)
+      || state.tombstones.has(parent.sessionId)
+      ? undefined
+      : state.sessions.get(parent.sessionId);
+    if (!parentStored?.session.origin) {
+      throw this.core.trustInternalError(new FlexHarnessValidationError(
+        `The parent of imported session "${sessionId}" must be a committed imported session.`,
+      ));
+    }
+    if ((parentStored.session.depth ?? 0) + 1 > FLEX_SESSION_IMPORT_MAX_DEPTH) {
+      throw this.core.trustInternalError(new FlexHarnessValidationError(
+        `Imported sessions nest at most ${FLEX_SESSION_IMPORT_MAX_DEPTH} levels deep.`,
+      ));
+    }
+    const referenced = parentStored.messages.some((message) =>
+      message.role === 'assistant'
+      && message.runId === parent.runId
+      && message.parts.some((part) =>
+        part.type === 'tool'
+        && part.toolCallId === parent.toolCallId
+        && part.childSessionId === sessionId));
+    if (!referenced) {
+      throw this.core.trustInternalError(new FlexHarnessValidationError(
+        `Parent run "${parent.runId}" has no tool call "${parent.toolCallId}" whose childSessionId is "${sessionId}".`,
+      ));
+    }
+    for (const stored of state.sessions.values()) {
+      if (
+        stored.session.parentSessionId === parent.sessionId
+        && stored.session.parentRunId === parent.runId
+        && stored.session.parentToolCallId === parent.toolCallId
+      ) {
+        throw this.core.trustInternalError(new FlexHarnessValidationError(
+          `Session "${stored.session.sessionId}" already belongs to tool call "${parent.toolCallId}".`,
+        ));
+      }
+    }
+    return parentStored;
+  }
+}