@modelprofile.com/flexharness 10.23.0 → 10.24.1

package/ts/classes.flexharness.deletion.ts

@@ -0,0 +1,616 @@
+import {
+  FlexHarnessAbortError,
+  FlexHarnessNotFoundError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import type {
+  IFlexAgentContextInvocation,
+  IFlexDeleteSessionGenerationCohortInput,
+  IFlexDeleteSessionGenerationCohortResult,
+  IFlexSession,
+  IFlexSessionGeneration,
+  IFlexSessionGenerationCohortEntry,
+  IFlexSessionTombstone,
+} from './interfaces.js';
+import { cloneSerializable } from './utils.json.js';
+import { publicSnapshot, requireTransferIdentifier } from './utils.transfer.js';
+import {
+  validateDeleteSessionGenerationCohortInput,
+  validateIdentifier,
+} from './utils.validation.js';
+import type {
+  IStoredSessionState,
+  IRetainedSessionCleanup,
+  IStorageState,
+  ISessionDeletionPlan,
+  IReservedSessionDeletion,
+} from './interfaces.flexharness.js';
+import { requireSessionGeneration, combineErrors } from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+function matchesSessionGeneration(
+  session: Pick<
+    IFlexSession | IFlexSessionTombstone,
+    'sessionGenerationId' | 'sessionGenerationSequence'
+  >,
+  expected: Readonly<IFlexSessionGeneration>,
+): boolean {
+  const actual = requireSessionGeneration(session);
+  return actual.sessionGenerationId === expected.sessionGenerationId
+    && actual.sessionGenerationSequence === expected.sessionGenerationSequence;
+}
+
+/**
+ * Session deletion: reservations, subtree tombstones and the cleanup of every domain a session
+ * owns.
+ */
+export class FlexHarnessSessionDeletion<TScope> {
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async deleteSessionGenerationCohort(
+    scopeId: string,
+    input: IFlexDeleteSessionGenerationCohortInput,
+  ): Promise<IFlexDeleteSessionGenerationCohortResult> {
+    const validated = validateDeleteSessionGenerationCohortInput(input);
+    requireTransferIdentifier(validated.root.sessionId, 'root.sessionId');
+    for (const entry of validated.authorizedBySessionId.values()) {
+      requireTransferIdentifier(entry.sessionId, 'authorizedCohort sessionId');
+    }
+    this.core.commands.assertNoAmbientSlashCommandTeardown({
+      scopeId,
+      sessionId: validated.root.sessionId,
+    });
+    const { scope, state } = await this.core.resolveState(scopeId);
+    this.core.commands.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
+    const plan = await this.core.withScopeMutationOwnership(state, async (): Promise<ISessionDeletionPlan> => {
+      const stored = state.sessions.get(validated.root.sessionId);
+      if (stored) {
+        if (!matchesSessionGeneration(stored.session, validated.root)) {
+          return { matched: false };
+        }
+        const subtree = this.collectSessionSubtree(state, validated.root.sessionId);
+        const descendantRoots = this.descendantTombstoneRoots(
+          state,
+          validated.root.sessionId,
+        );
+        this.assertAuthorizedSessionGenerationCohort(
+          [
+            ...subtree.map((entry) => entry.session),
+            ...this.tombstonesForRoots(state, descendantRoots),
+          ],
+          validated.authorizedBySessionId,
+        );
+        const reservation = await this.core.mutateScopeOwned(state, () =>
+          this.reserveLiveSessionDeletion(
+            state,
+            validated.root.sessionId,
+            stored,
+            subtree,
+            descendantRoots,
+          ));
+        return {
+          matched: true,
+          deletion: this.startReservedSessionDeletion(
+            state,
+            scopeId,
+            scope.scope,
+            validated.root.sessionId,
+            reservation,
+          ),
+        };
+      }
+      const tombstone = state.tombstones.get(validated.root.sessionId);
+      if (!tombstone || !matchesSessionGeneration(tombstone, validated.root)) {
+        return { matched: false };
+      }
+      this.core.imports.assertNoCommittingSessionImport(state, validated.root.sessionId);
+      const rootSessionId = tombstone.rootSessionId ?? tombstone.sessionId;
+      const descendantRoots = this.descendantTombstoneRoots(state, rootSessionId);
+      this.assertAuthorizedSessionGenerationCohort(
+        this.tombstonesForRoots(state, [rootSessionId, ...descendantRoots]),
+        validated.authorizedBySessionId,
+      );
+      return {
+        matched: true,
+        deletion: this.startSessionDeletion(
+          state,
+          scopeId,
+          scope.scope,
+          validated.root.sessionId,
+        ),
+      };
+    });
+    if (!plan.matched) return publicSnapshot({ matched: false });
+    if (!plan.deletion) throw new Error('Matched session deletion has no cleanup operation.');
+    await plan.deletion;
+    return publicSnapshot({ matched: true });
+  }
+
+  public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
+    this.core.commands.assertNoAmbientSlashCommandTeardown({ scopeId, sessionId });
+    const { scope, state } = await this.core.resolveState(scopeId);
+    this.core.commands.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
+    validateIdentifier(sessionId, 'sessionId');
+    await state.scopeQueue;
+    this.core.imports.assertNoCommittingSessionImport(state, sessionId);
+    return this.startSessionDeletion(state, scopeId, scope.scope, sessionId);
+  }
+
+  private startSessionDeletion(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+  ): Promise<void> {
+    const deletionKey = state.tombstones.get(sessionId)?.rootSessionId ?? sessionId;
+    return this.registerSessionDeletion(
+      state,
+      deletionKey,
+      () => this.deleteSessionInternal(state, scopeId, scope, sessionId),
+    );
+  }
+
+  private startReservedSessionDeletion(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+    reservation: IReservedSessionDeletion,
+  ): Promise<void> {
+    return this.registerSessionDeletion(
+      state,
+      sessionId,
+      () => this.finishReservedSessionDeletion(
+        state,
+        scopeId,
+        scope,
+        sessionId,
+        reservation,
+      ),
+    );
+  }
+
+  private registerSessionDeletion(
+    state: IStorageState,
+    deletionKey: string,
+    operation: () => Promise<void>,
+  ): Promise<void> {
+    const existingDeletion = state.sessionDeletions.get(deletionKey);
+    if (existingDeletion) return existingDeletion;
+    let deletion!: Promise<void>;
+    deletion = operation().finally(() => {
+      if (state.sessionDeletions.get(deletionKey) === deletion) {
+        state.sessionDeletions.delete(deletionKey);
+      }
+    });
+    state.sessionDeletions.set(deletionKey, deletion);
+    return deletion;
+  }
+
+  private assertAuthorizedSessionGenerationCohort(
+    entries: readonly (IFlexSession | IFlexSessionTombstone)[],
+    authorizedBySessionId: ReadonlyMap<
+      string,
+      Readonly<IFlexSessionGenerationCohortEntry>
+    >,
+  ): void {
+    for (const entry of entries) {
+      const authorized = authorizedBySessionId.get(entry.sessionId);
+      if (!authorized || !matchesSessionGeneration(entry, authorized)) {
+        throw new FlexHarnessValidationError(
+          `authorizedCohort does not authorize the exact generation of session "${entry.sessionId}".`,
+        );
+      }
+    }
+  }
+
+  private reserveLiveSessionDeletion(
+    state: IStorageState,
+    sessionId: string,
+    stored: IStoredSessionState,
+    subtree: readonly IStoredSessionState[],
+    descendantRoots: readonly string[],
+  ): IReservedSessionDeletion {
+    if (state.sessions.get(sessionId) !== stored) {
+      throw new FlexHarnessNotFoundError('Session', sessionId);
+    }
+    const rootDepth = stored.session.depth ?? 0;
+    const deletedAt = new Date().toISOString();
+    const deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
+    const provenanceBySessionId = new Map(subtree.map((entry) => [
+      entry.session.sessionId,
+      this.core.subagentTasks.createSubagentProvenance(state, entry.session),
+    ]));
+    for (const entry of subtree) {
+      const entrySessionId = entry.session.sessionId;
+      const subagent = provenanceBySessionId.get(entrySessionId);
+      state.sessions.delete(entrySessionId);
+      state.retainedSessionCleanups.set(entrySessionId, {
+        stored: entry,
+        domainsCompleted: false,
+      });
+      state.tombstones.set(entrySessionId, {
+        sessionId: entrySessionId,
+        ...requireSessionGeneration(entry.session),
+        deletedAt,
+        rootSessionId: sessionId,
+        depth: (entry.session.depth ?? rootDepth) - rootDepth,
+        ...(entry.session.parentSessionId === undefined
+          ? {}
+          : { parentSessionId: entry.session.parentSessionId }),
+        ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
+        ...(entry.session.origin === undefined ? {} : { imported: true as const }),
+      });
+    }
+    return {
+      deletedSessions,
+      descendantRoots: [...descendantRoots],
+    };
+  }
+
+  public async deleteSessionInternal(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+  ): Promise<void> {
+    const existingTombstone = state.tombstones.get(sessionId);
+    if (existingTombstone) {
+      const rootSessionId = existingTombstone.rootSessionId ?? existingTombstone.sessionId;
+      const descendantRoots = this.descendantTombstoneRoots(state, sessionId)
+        .filter((candidate) => candidate !== rootSessionId);
+      try {
+        const orphanErrors = await this.core.lifecycle.closeOrphanedResources(state.storageKey);
+        if (orphanErrors.length > 0) throw combineErrors(orphanErrors);
+        for (const descendantRoot of descendantRoots) {
+          await this.finishTombstoneCleanup(
+            state,
+            descendantRoot,
+            scopeId,
+            { scopeId, scope },
+          );
+        }
+        await this.finishTombstoneCleanup(state, rootSessionId, scopeId, { scopeId, scope });
+      } catch (error) {
+        throw this.core.projectOperationError(error, 'persistence', scopeId, sessionId, 'session-delete');
+      }
+      return;
+    }
+    const stored = this.core.requireSession(state, sessionId);
+    const reservation = await this.core.mutateScope(state, () => {
+      const subtree = this.collectSessionSubtree(state, sessionId);
+      const descendantRoots = this.descendantTombstoneRoots(state, sessionId);
+      return this.reserveLiveSessionDeletion(
+        state,
+        sessionId,
+        stored,
+        subtree,
+        descendantRoots,
+      );
+    });
+    await this.finishReservedSessionDeletion(state, scopeId, scope, sessionId, reservation);
+  }
+
+  private async finishReservedSessionDeletion(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+    reservation: IReservedSessionDeletion,
+  ): Promise<void> {
+    const { deletedSessions, descendantRoots } = reservation;
+    const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
+    const configurationSettlement = this.core.configurations.abortSessionConfigurations(
+      state.storageKey,
+      reason,
+      new Set(deletedSessions.map((deleted) => deleted.sessionId)),
+    );
+    if (configurationSettlement) await configurationSettlement;
+    const slashCommandErrors: unknown[] = [];
+    for (const deleted of deletedSessions) {
+      const listingSettlement = this.core.commands.abortSlashCommandListings(
+        state.storageKey,
+        reason,
+        deleted.sessionId,
+      );
+      if (listingSettlement) await listingSettlement;
+      await this.core.commands.abortSlashCommandExecutions(
+        state.storageKey,
+        reason,
+        slashCommandErrors,
+        deleted.sessionId,
+      );
+    }
+    const childFirstDeletedSessions = [...deletedSessions].sort((left, right) =>
+      (right.depth ?? 0) - (left.depth ?? 0)
+      || left.sessionId.localeCompare(right.sessionId));
+    for (const deleted of childFirstDeletedSessions) {
+      const active = state.activeRuns.get(deleted.sessionId);
+      if (active) {
+        this.core.runs.cancelRun(
+          active,
+          reason,
+          this.core.compaction.createCompactorContext(scopeId, scope, state.storageKey, deleted.sessionId),
+        );
+      }
+    }
+    try {
+      const orphanErrors = [
+        ...slashCommandErrors,
+        ...await this.core.lifecycle.closeOrphanedResources(state.storageKey),
+      ];
+      if (orphanErrors.length > 0) throw combineErrors(orphanErrors);
+      for (const descendantRoot of descendantRoots) {
+        await this.finishTombstoneCleanup(
+          state,
+          descendantRoot,
+          scopeId,
+          { scopeId, scope },
+        );
+      }
+      await this.finishTombstoneCleanup(state, sessionId, scopeId, { scopeId, scope });
+    } catch (error) {
+      throw this.core.projectOperationError(error, 'persistence', scopeId, sessionId, 'session-delete');
+    }
+    for (const deleted of childFirstDeletedSessions) {
+      this.core.emitEvent(scopeId, deleted, {
+        type: 'session.deleted',
+        session: publicSnapshot(deleted),
+      });
+    }
+  }
+
+  public async cleanupSessionDomains(
+    state: IStorageState,
+    tombstone: IFlexSessionTombstone,
+  ): Promise<void> {
+    const storageKey = state.storageKey;
+    const sessionId = tombstone.sessionId;
+    const projectManagementCleanup = async (): Promise<void> => {
+      await this.core.projects.projectManagementQueues.get(
+        this.core.projects.projectManagementKey(storageKey, sessionId),
+      );
+      await this.core.projects.tombstoneProjectManagementSession(
+        state,
+        tombstone,
+      );
+    };
+    const resultStore = this.core.stores.results;
+    const resultCleanup = async (): Promise<void> => {
+      // A result being saved for the session is written before its results are deleted.
+      await this.core.results.resultQueues.get(this.core.results.resultQueueKey(storageKey, sessionId));
+      await resultStore!.deleteSession(storageKey, sessionId);
+    };
+    const results = await Promise.allSettled([
+      this.core.stores.agentEvents.deleteSession(storageKey, sessionId),
+      this.core.stores.jobs.deleteSession(storageKey, sessionId),
+      this.core.stores.projections.deleteSession(storageKey, sessionId),
+      this.core.stores.permissions.deleteSession(storageKey, sessionId),
+      ...(resultStore ? [resultCleanup()] : []),
+      // An imported session refuses every project-management write, so it has no state to fence.
+      ...(tombstone.imported ? [] : [projectManagementCleanup()]),
+    ]);
+    const errors = results
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (errors.length > 0) throw combineErrors(errors);
+  }
+
+  private collectSessionSubtree(
+    state: IStorageState,
+    rootSessionId: string,
+  ): IStoredSessionState[] {
+    const subtree: IStoredSessionState[] = [];
+    const pending = [rootSessionId];
+    const seen = new Set<string>();
+    while (pending.length > 0) {
+      const sessionId = pending.pop()!;
+      if (seen.has(sessionId)) {
+        throw new FlexHarnessValidationError('Session relationships contain a cycle.');
+      }
+      seen.add(sessionId);
+      const stored = state.sessions.get(sessionId);
+      if (!stored) continue;
+      subtree.push(stored);
+      const children = [...state.sessions.values()]
+        .filter((candidate) => candidate.session.parentSessionId === sessionId)
+        .map((candidate) => candidate.session.sessionId)
+        .sort()
+        .reverse();
+      pending.push(...children);
+    }
+    return subtree;
+  }
+
+  public tombstoneGroup(
+    state: IStorageState,
+    rootSessionId: string,
+  ): IFlexSessionTombstone[] {
+    return [...state.tombstones.values()]
+      .filter((tombstone) =>
+        (tombstone.rootSessionId ?? tombstone.sessionId) === rootSessionId)
+      .sort((left, right) =>
+        (right.depth ?? 0) - (left.depth ?? 0)
+        || left.sessionId.localeCompare(right.sessionId));
+  }
+
+  private tombstonesForRoots(
+    state: IStorageState,
+    rootSessionIds: readonly string[],
+  ): IFlexSessionTombstone[] {
+    return [...new Set(rootSessionIds)]
+      .flatMap((rootSessionId) => this.tombstoneGroup(state, rootSessionId));
+  }
+
+  public descendantTombstoneRoots(
+    state: IStorageState,
+    ancestorSessionId: string,
+  ): string[] {
+    return [...new Set([...state.tombstones.values()]
+      .map((tombstone) => tombstone.rootSessionId ?? tombstone.sessionId)
+      .filter((rootSessionId) =>
+        rootSessionId !== ancestorSessionId
+        && this.core.isSessionAncestor(state, ancestorSessionId, rootSessionId)))]
+      .sort((left, right) =>
+        this.core.sessionAncestryDepth(state, right) - this.core.sessionAncestryDepth(state, left)
+        || left.localeCompare(right));
+  }
+
+  public orderTombstoneRootsChildFirst(
+    state: IStorageState,
+    rootSessionIds: readonly string[],
+  ): string[] {
+    return [...rootSessionIds].sort((left, right) =>
+      this.core.sessionAncestryDepth(state, right) - this.core.sessionAncestryDepth(state, left)
+      || left.localeCompare(right));
+  }
+
+  public finishTombstoneCleanup(
+    state: IStorageState,
+    rootSessionId: string,
+    scopeId: string,
+    invocation?: { scopeId: string; scope: TScope },
+  ): Promise<void> {
+    const existing = state.tombstoneCleanups.get(rootSessionId);
+    if (existing) return existing;
+    let cleanup!: Promise<void>;
+    cleanup = this.finishTombstoneCleanupInternal(
+      state,
+      rootSessionId,
+      scopeId,
+      invocation,
+    ).finally(() => {
+      if (state.tombstoneCleanups.get(rootSessionId) === cleanup) {
+        state.tombstoneCleanups.delete(rootSessionId);
+      }
+    });
+    state.tombstoneCleanups.set(rootSessionId, cleanup);
+    return cleanup;
+  }
+
+  private async finishTombstoneCleanupInternal(
+    state: IStorageState,
+    rootSessionId: string,
+    scopeId: string,
+    invocation?: { scopeId: string; scope: TScope },
+  ): Promise<void> {
+    for (const descendantRoot of this.descendantTombstoneRoots(state, rootSessionId)) {
+      await this.finishTombstoneCleanup(state, descendantRoot, scopeId, invocation);
+    }
+    const group = this.tombstoneGroup(state, rootSessionId);
+    if (group.length === 0) return;
+    const exactInvocation = invocation ?? {
+      scopeId: state.scopeContext.scopeId,
+      scope: state.scopeContext.scope as TScope,
+    };
+    const groupIds = new Set(group.map((tombstone) => tombstone.sessionId));
+    const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
+    const contextFor = (
+      sessionId: string,
+      retained?: IRetainedSessionCleanup,
+    ): IFlexAgentContextInvocation<TScope> | undefined => exactInvocation
+      ? this.core.compaction.createCompactorContext(
+          exactInvocation.scopeId,
+          exactInvocation.scope,
+          state.storageKey,
+          sessionId,
+        )
+      : retained?.stored.compactorContext as IFlexAgentContextInvocation<TScope> | undefined;
+    for (const sessionId of groupIds) {
+      const retained = state.retainedSessionCleanups.get(sessionId);
+      const context = contextFor(sessionId, retained);
+      if (retained) {
+        this.core.compaction.abortCompactorLifecycle(retained.stored, reason);
+        this.core.prompts.cancelStoredPromptQueue(retained.stored, reason, undefined, context);
+      }
+      const run = state.activeRuns.get(sessionId);
+      if (run) this.core.runs.cancelRun(run, reason, context);
+    }
+    await Promise.allSettled([...groupIds]
+      .map((sessionId) => state.sessionInitializations.get(sessionId))
+      .filter((completion): completion is Promise<void> => completion !== undefined));
+    for (const tombstone of group) {
+      const sessionId = tombstone.sessionId;
+      const retained = state.retainedSessionCleanups.get(sessionId);
+      const errors: unknown[] = [];
+      const run = state.activeRuns.get(sessionId);
+      const context = contextFor(sessionId, retained);
+      if (retained && !retained.stored.agentSessionAbortCompleted) {
+        try {
+          await this.core.lifecycle.abortStoredSession(retained.stored, reason, context);
+        } catch (error) {
+          errors.push(this.core.projectOperationError(
+            error,
+            'agentSession',
+            scopeId,
+            sessionId,
+            'session-delete',
+          ));
+        }
+      }
+      if (run) {
+        const settled = await Promise.allSettled([run.completion]);
+        if (settled[0].status === 'rejected') {
+          this.core.appendUnexpectedErrors(errors, settled[0].reason);
+        }
+      }
+      errors.push(...await this.core.admission.settleDelegatedRunAdmissionOwners(
+        this.core.admission.delegatedRunAdmissionOwnersForGeneration(state, tombstone),
+      ));
+      if (retained) {
+        if (retained.stored.promptQueueDrain) {
+          const settled = await Promise.allSettled([retained.stored.promptQueueDrain]);
+          if (settled[0].status === 'rejected') errors.push(settled[0].reason);
+        }
+        try {
+          await this.core.lifecycle.closeStoredSession(retained.stored, context);
+        } catch (error) {
+          this.core.appendUnexpectedErrors(errors, this.core.projectOperationError(
+            error,
+            'toolCleanup',
+            scopeId,
+            sessionId,
+            'session-delete',
+          ));
+        }
+      }
+      if (errors.length > 0) {
+        if (
+          retained
+          && state.lifecycle === 'retired'
+          && !this.core.lifecycle.storedSessionCleanupCompleted(retained.stored)
+        ) this.core.lifecycle.orphanedStoredSessions.add(retained.stored);
+        throw combineErrors(errors);
+      }
+      if (retained) this.core.prompts.purgeStoredPromptQueue(retained.stored);
+      if (!retained?.domainsCompleted) {
+        if (this.core.lifecycle.hasOrphanedSessionResources(state.storageKey, sessionId)) {
+          throw new Error(`Session "${sessionId}" still has runtime cleanup ownership.`);
+        }
+        const releaseContext = exactInvocation ?? retained?.stored.compactorContext as
+          IFlexAgentContextInvocation<TScope> | undefined;
+        if (!releaseContext) {
+          throw new FlexHarnessValidationError(
+            'Tombstone cleanup requires its exact scope context before deleting projection data.',
+          );
+        }
+        await this.core.reversions.releaseDeletedSessionReversions(
+          state,
+          state.storageKey,
+          tombstone,
+          releaseContext.scopeId,
+          releaseContext.scope,
+          retained?.stored,
+        );
+        await this.cleanupSessionDomains(state, tombstone);
+        if (retained) retained.domainsCompleted = true;
+      }
+    }
+    await this.core.mutateScope(state, () => {
+      for (const tombstone of group) {
+        state.tombstones.delete(tombstone.sessionId);
+        state.retainedSessionCleanups.delete(tombstone.sessionId);
+      }
+    }, true);
+  }
+}