@modelprofile.com/flexharness 10.23.0 → 10.24.1

package/ts/classes.flexharness.sessions.ts

@@ -0,0 +1,483 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessSessionBusyError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
+  type IFlexCreateSessionOptions,
+  type IFlexEventArchiveMetadata,
+  type IFlexMessage,
+  type IFlexMessagePage,
+  type IFlexMessagePageOptions,
+  type IFlexSession,
+  type IFlexSessionView,
+  type IFlexSessionMetrics,
+  type IFlexSessionTombstone,
+  type IFlexUpdateSessionOptions,
+  type IJsonObject,
+} from './interfaces.js';
+import { cloneSerializable } from './utils.json.js';
+import {
+  createBoundedTransferMessage,
+  jsonBytes,
+  maxMessagePageCursorBytes,
+  maxMessagePageSize,
+  maxTransferPageBytes,
+  publicSnapshot,
+  requireTransferIdentifier,
+} from './utils.transfer.js';
+import {
+  validateIdentifier,
+  validateSessionGenerationId,
+  validateSessionConfigurationRef,
+  validateUpdateSessionOptions,
+  validateUtf8String,
+} from './utils.validation.js';
+import { sessionMetricsView } from './utils.sessionmetrics.js';
+import {
+  createSessionGenerationId,
+  requireSessionGeneration,
+  combineErrors,
+} from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/**
+ * Consecutive waits a session view makes for queued writes and open sections to settle. Each wait
+ * ends only when real work finishes, so the bound limits starvation by a session that never stops
+ * changing, not the time one slow save may take.
+ */
+const maxSessionViewPasses = 64;
+
+/** Sessions and their messages: listing, creation, updates, views and message pages. */
+export class FlexHarnessSessions<TScope> {
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async listSessions(scopeId: string): Promise<IFlexSession[]> {
+    const { state } = await this.core.resolveState(scopeId);
+    await state.scopeQueue;
+    this.core.assertOpen();
+    this.core.assertStateAcceptingWork(state);
+    return publicSnapshot([...state.sessions.values()]
+      .filter((stored) => !state.initializingSessions.has(stored.session.sessionId))
+      .map((stored) => stored.session)
+      .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)));
+  }
+
+  public async createSession(
+    scopeId: string,
+    options: IFlexCreateSessionOptions = {},
+  ): Promise<IFlexSession> {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new FlexHarnessValidationError('createSession options must be a plain object.');
+    }
+    const unsupported = Object.keys(options).find(
+      (key) => !['sessionId', 'sessionGenerationId', 'configurationRef', 'title'].includes(key),
+    );
+    if (unsupported) throw new FlexHarnessValidationError(`createSession does not support "${unsupported}".`);
+    const requestedSessionGenerationId = options.sessionGenerationId;
+    if (requestedSessionGenerationId !== undefined) {
+      validateSessionGenerationId(requestedSessionGenerationId);
+    }
+    if (options.configurationRef !== undefined) validateSessionConfigurationRef(options.configurationRef);
+    const resolved = await this.core.resolveState(scopeId);
+    const sessionId = options.sessionId ?? plugins.crypto.randomUUID();
+    validateIdentifier(sessionId, 'sessionId');
+    requireTransferIdentifier(sessionId, 'sessionId');
+    if (options.title !== undefined) {
+      validateUtf8String(
+        options.title,
+        'title',
+        FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes,
+        true,
+      );
+    }
+    await resolved.state.scopeQueue;
+    if (
+      resolved.state.sessions.has(sessionId)
+      || resolved.state.tombstones.has(sessionId)
+      || resolved.state.initializingSessions.has(sessionId)
+    ) {
+      throw new FlexHarnessValidationError(`Session "${sessionId}" already exists or is being deleted.`);
+    }
+    resolved.state.initializingSessions.add(sessionId);
+    let resolveInitialization!: () => void;
+    const initializationCompletion = new Promise<void>((resolve) => {
+      resolveInitialization = resolve;
+    });
+    let initializationCompleted = false;
+    const completeInitialization = () => {
+      if (initializationCompleted) return;
+      initializationCompleted = true;
+      if (resolved.state.sessionInitializations.get(sessionId) === initializationCompletion) {
+        resolved.state.sessionInitializations.delete(sessionId);
+      }
+      resolveInitialization();
+    };
+    resolved.state.sessionInitializations.set(sessionId, initializationCompletion);
+    let scopeReserved = false;
+    let metadata!: IFlexSession;
+    try {
+      await this.core.mutateScope(resolved.state, () => {
+        if (resolved.state.sessions.has(sessionId) || resolved.state.tombstones.has(sessionId)) {
+          throw new FlexHarnessValidationError(`Session "${sessionId}" already exists or is being deleted.`);
+        }
+        const timestamp = new Date().toISOString();
+        metadata = {
+          scopeId,
+          sessionId,
+          sessionGenerationId: requestedSessionGenerationId ?? createSessionGenerationId(),
+          sessionGenerationSequence: resolved.state.revision + 1,
+          ...(options.configurationRef === undefined ? {} : { configurationRef: options.configurationRef }),
+          ...(options.title ? { title: options.title } : {}),
+          createdAt: timestamp,
+          updatedAt: timestamp,
+          status: 'idle',
+          activity: { status: 'idle' },
+          depth: 0,
+        };
+        resolved.state.sessions.set(
+          sessionId,
+          this.core.createUninitializedStoredSession(metadata, resolved.state.storageKey),
+        );
+      });
+      scopeReserved = true;
+      const placeholder = resolved.state.sessions.get(sessionId)!;
+      const initialization = this.core.loadSessionRuntime(
+        resolved.state,
+        metadata,
+        scopeId,
+        resolved.scope.scope,
+        placeholder.compactorLifecycleController,
+        true,
+      );
+      const loaded = await initialization;
+      if (resolved.state.sessions.get(sessionId) !== placeholder) {
+        const aborted = new FlexHarnessAbortError('The session was deleted while it was being created.');
+        try {
+          await this.core.lifecycle.closeStoredSession(loaded);
+        } catch (closeError) {
+          this.core.lifecycle.orphanedStoredSessions.add(loaded);
+          throw combineErrors([aborted, closeError]);
+        }
+        throw aborted;
+      }
+      resolved.state.sessions.set(sessionId, loaded);
+    } catch (error) {
+      const projectedError = this.core.projectOperationError(
+        error,
+        'agentSession',
+        scopeId,
+        sessionId,
+        'session-create',
+      );
+      scopeReserved ||= resolved.state.sessions.has(sessionId);
+      if (!scopeReserved) throw projectedError;
+      const tombstone: IFlexSessionTombstone = {
+        sessionId,
+        ...requireSessionGeneration(metadata),
+        deletedAt: new Date().toISOString(),
+        rootSessionId: sessionId,
+        depth: 0,
+      };
+      let tombstoneCommitted = false;
+      let domainCleanupCompleted = false;
+      try {
+        await this.core.mutateScope(resolved.state, () => {
+          resolved.state.sessions.delete(sessionId);
+          resolved.state.tombstones.set(sessionId, tombstone);
+        }, true);
+        tombstoneCommitted = true;
+        completeInitialization();
+        await this.core.deletion.finishTombstoneCleanup(
+          resolved.state,
+          sessionId,
+          scopeId,
+          { scopeId, scope: resolved.scope.scope },
+        );
+        domainCleanupCompleted = true;
+      } catch (cleanupError) {
+        const projectedCleanup = this.core.projectOperationError(
+          cleanupError,
+          'persistence',
+          scopeId,
+          sessionId,
+          'session-create-cleanup',
+        );
+        if (!tombstoneCommitted || domainCleanupCompleted) {
+          resolved.state.sessions.delete(sessionId);
+          const stateLoad = this.core.stateLoads.get(resolved.state.storageKey);
+          if (stateLoad) {
+            completeInitialization();
+            try {
+              await this.core.lifecycle.drainStorage(
+                resolved.state.storageKey,
+                stateLoad,
+                this.core.trustInternalError(new FlexHarnessAbortError(
+                  'The session namespace was fenced after uncertain creation cleanup.',
+                )),
+                { scopeId, scope: resolved.scope.scope },
+              );
+            } catch {
+              // The projected creation and cleanup errors remain safe for the caller.
+            }
+          }
+        }
+        throw combineErrors([projectedError, projectedCleanup]);
+      }
+      throw projectedError;
+    } finally {
+      resolved.state.initializingSessions.delete(sessionId);
+      completeInitialization();
+    }
+    const result = publicSnapshot(metadata);
+    this.core.emitEvent(scopeId, metadata, { type: 'session.created', session: result });
+    return result;
+  }
+
+  public async getSession(scopeId: string, sessionId: string): Promise<IFlexSession> {
+    const { state } = await this.core.resolveState(scopeId);
+    await state.scopeQueue;
+    this.core.assertStateAcceptingWork(state);
+    return publicSnapshot(this.core.requireSession(state, sessionId).session);
+  }
+
+  public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
+    const { state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.core.assertStateAcceptingWork(state);
+    if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
+    return publicSnapshot(sessionMetricsView(stored.metrics));
+  }
+
+  public async updateSession(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexUpdateSessionOptions,
+  ): Promise<IFlexSession> {
+    validateUpdateSessionOptions(options);
+    const { state } = await this.core.resolveState(scopeId);
+    let result!: IFlexSession;
+    await this.core.mutateScope(state, () => {
+      const stored = Object.prototype.hasOwnProperty.call(options, 'archived')
+        ? this.core.requireMutableSession(state, sessionId)
+        : this.core.requireSession(state, sessionId);
+      const timestamp = new Date().toISOString();
+      if (Object.prototype.hasOwnProperty.call(options, 'title')) {
+        if (options.title === null) delete stored.session.title;
+        else stored.session.title = options.title!;
+      }
+      if (options.archived === true) stored.session.archivedAt ??= timestamp;
+      else if (options.archived === false) delete stored.session.archivedAt;
+      stored.session.updatedAt = timestamp;
+      result = publicSnapshot(stored.session);
+    });
+    this.core.emitEvent(scopeId, result, { type: 'session.updated', session: result });
+    return result;
+  }
+
+  public async getSessionView(scopeId: string, sessionId: string): Promise<IFlexSessionView> {
+    const { state } = await this.core.resolveState(scopeId);
+    let stored = this.core.requireSession(state, sessionId);
+    for (let pass = 0; ; pass++) {
+      if (pass === maxSessionViewPasses) {
+        throw new FlexHarnessSessionBusyError(
+          sessionId,
+          `kept changing through ${maxSessionViewPasses} consecutive waits for a settled view`,
+        );
+      }
+      const scopeQueue = state.scopeQueue;
+      const projectionQueue = stored.projectionQueue;
+      const publications = [...(state.publications.get(sessionId) ?? [])];
+      await Promise.all([scopeQueue, projectionQueue, ...publications]);
+      this.core.assertStateAcceptingWork(state);
+      stored = this.core.requireSession(state, sessionId);
+      if (
+        state.scopeQueue === scopeQueue
+        && stored.projectionQueue === projectionQueue
+        && !state.publications.get(sessionId)?.size
+      ) break;
+    }
+    const run = state.activeRuns.get(sessionId);
+    const messages = this.core.visibleMessages(stored).map((message) => (
+      run && run.stored === stored && message.messageId === run.assistantMessageId
+        && message.status === 'streaming'
+        ? { ...message, parts: run.callbackParts }
+        : message
+    ));
+    return publicSnapshot({
+      session: stored.session,
+      messages,
+      pendingPermissions: [...state.pendingPermissions.values()]
+        .map((pending) => pending.request)
+        .filter((request) => request.sessionId === sessionId)
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt)),
+      sequence: this.core.sequence,
+    });
+  }
+
+  public async getMessages(scopeId: string, sessionId: string): Promise<IFlexMessage[]> {
+    const { state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.core.assertStateAcceptingWork(state);
+    return publicSnapshot(this.core.visibleMessages(stored));
+  }
+
+  public async listMessagePage(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexMessagePageOptions = {},
+  ): Promise<IFlexMessagePage> {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new FlexHarnessValidationError('Message page options must be a plain object.');
+    }
+    const unsupported = Object.keys(options).find((key) => key !== 'limit' && key !== 'before');
+    if (unsupported) throw new FlexHarnessValidationError(`Message page options do not support "${unsupported}".`);
+    const limit = options.limit ?? maxMessagePageSize;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxMessagePageSize) {
+      throw new FlexHarnessValidationError(`Message page limit must be an integer from 1 through ${maxMessagePageSize}.`);
+    }
+    if (
+      options.before !== undefined
+      && (typeof options.before !== 'string'
+        || !options.before
+        || Buffer.byteLength(options.before, 'utf8') > maxMessagePageCursorBytes)
+    ) {
+      throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    }
+    const { state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.core.assertStateAcceptingWork(state);
+    const namespace = this.core.messageCursorNamespace(state.storageKey);
+    const visibleMessages = this.core.visibleMessages(stored);
+    let end = visibleMessages.length;
+    if (options.before !== undefined) {
+      const cursor = this.core.parseMessageCursor(options.before);
+      if (cursor.namespace !== namespace || cursor.sessionId !== sessionId) {
+        throw new FlexHarnessValidationError('Message page cursor is invalid.');
+      }
+      const anchor = visibleMessages.findIndex((message) => message.messageId === cursor.anchorMessageId);
+      if (anchor < 0) throw new FlexHarnessValidationError('Message page cursor is stale.');
+      end = anchor;
+    }
+    let start = end;
+    let messages: IFlexMessage[] = [];
+    for (let index = end - 1; index >= 0 && messages.length < limit; index--) {
+      const candidate = createBoundedTransferMessage(visibleMessages[index]);
+      const candidateMessages = [candidate, ...messages];
+      const nextCursor = index > 0
+        ? this.core.createMessageCursor(namespace, sessionId, candidate.messageId)
+        : undefined;
+      const candidatePage: IFlexMessagePage = {
+        messages: candidateMessages,
+        startIndex: index,
+        ...(nextCursor ? { nextCursor } : {}),
+      };
+      if (jsonBytes(candidatePage) > maxTransferPageBytes) break;
+      start = index;
+      messages = candidateMessages;
+    }
+    if (messages.length === 0 && end > 0) {
+      throw new FlexHarnessValidationError('Stored message exceeds the page transfer limit.');
+    }
+    const nextCursor = start > 0
+      ? this.core.createMessageCursor(namespace, sessionId, messages[0].messageId)
+      : undefined;
+    return publicSnapshot({ messages, startIndex: start, ...(nextCursor ? { nextCursor } : {}) });
+  }
+
+  public async getMessage(
+    scopeId: string,
+    sessionId: string,
+    messageId: string,
+  ): Promise<IFlexMessage> {
+    validateIdentifier(messageId, 'messageId');
+    requireTransferIdentifier(messageId, 'messageId');
+    const { state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.core.assertStateAcceptingWork(state);
+    return publicSnapshot(createBoundedTransferMessage(this.core.requireMessage(stored, messageId)));
+  }
+
+  public async pushRuntimeEvent(
+    scopeId: string,
+    sessionId: string,
+    event: IJsonObject & { type: string },
+  ): Promise<void> {
+    this.core.validateRuntimeEvent(event);
+    const { scope, state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    this.core.assertSessionWritable(stored);
+    this.core.assertStateAcceptingWork(state);
+    try {
+      await this.core.compaction.withCompactorContext(
+        this.core.compaction.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
+        () => stored.agentSession.pushRuntimeEvent(cloneSerializable(event)),
+      );
+    } catch (error) {
+      throw this.core.projectOperationError(error, 'agentSession', scopeId, sessionId, 'runtime-event');
+    }
+  }
+
+  public async archiveSessionEvents(
+    scopeId: string,
+    sessionId: string,
+    compactionEventId?: string,
+  ): Promise<IFlexEventArchiveMetadata | undefined> {
+    if (compactionEventId !== undefined) {
+      validateIdentifier(compactionEventId, 'compactionEventId');
+      requireTransferIdentifier(compactionEventId, 'compactionEventId');
+    }
+    const { scope, state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    this.core.assertSessionWritable(stored);
+    this.core.assertStateAcceptingWork(state);
+    this.core.commands.requireSessionAvailableForSlashCommand(state, stored, 'archive');
+    const compaction = compactionEventId === undefined
+      ? [...stored.agentSession.getEvents()].reverse().find((event) =>
+          event.type === 'context-compaction')
+      : stored.agentSession.getEvents().find((event) =>
+          event.type === 'context-compaction' && event.id === compactionEventId);
+    if (!compaction || compaction.type !== 'context-compaction') return undefined;
+    let archive;
+    try {
+      archive = await stored.agentSession.archiveCompactedEvents(compaction.id);
+    } catch (error) {
+      throw this.core.projectOperationError(error, 'agentSession', scopeId, sessionId, 'archive');
+    }
+    if (!archive) return undefined;
+    let branchCommitted = false;
+    try {
+      const archivedIds = new Set(archive.events.map((event) => event.id));
+      await this.core.mutateProjection(state, stored, () => {
+        branchCommitted = this.core.reversions.commitRevertedBranchState(stored);
+        for (const segment of stored.reversionSegments) {
+          if (segment.eventIds.some((eventId) => archivedIds.has(eventId))) {
+            segment.contextAvailable = false;
+          }
+        }
+        this.core.reversions.pruneReversionState(stored);
+      }, true);
+    } catch (error) {
+      throw this.core.projectOperationError(error, 'persistence', scopeId, sessionId, 'archive-horizon');
+    }
+    if (branchCommitted) {
+      this.core.emitEvent(scopeId, stored.session, {
+        type: 'session.history.changed',
+        direction: 'branch',
+      });
+    }
+    await this.core.reversions.drainReversionReleases(state, stored, scopeId, scope.scope, false);
+    return publicSnapshot({
+      archiveId: this.core.boundedIdentifier(archive.archiveId, 'archiveId'),
+      sessionId: this.core.boundedIdentifier(archive.sessionId, 'sessionId'),
+      createdAt: new Date(archive.createdAt).toISOString(),
+      eventCount: archive.events.length,
+    });
+  }
+}