@modelprofile.com/flexharness 10.24.0 → 11.0.0

package/ts/classes.flexharness.compaction.ts

@@ -0,0 +1,167 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessSlashCommandReentryError,
+  FlexHarnessSlashCommandUnavailableError,
+} from './errors.js';
+import type {
+  IFlexAgentContextCompactionOptions,
+  IFlexAgentContextInvocation,
+  IFlexCompactSessionOptions,
+} from './interfaces.js';
+import { validateCompactSessionOptions } from './utils.validation.js';
+import type {
+  ICompactorInvocation,
+  IStoredSessionState,
+  IStorageState,
+  IActiveRun,
+} from './interfaces.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** Compaction hooks: compactor contexts and session compaction. */
+export class FlexHarnessCompaction<TScope> {
+  public readonly compactorInvocationContext = new plugins.AsyncLocalStorage<
+    ICompactorInvocation<TScope>
+  >();
+  public readonly deferredCompactorContexts = new WeakMap<
+    IFlexAgentContextInvocation<unknown>,
+    IFlexAgentContextInvocation<unknown>
+  >();
+
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async compactSession(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexCompactSessionOptions = {},
+  ): Promise<void> {
+    const { modelHint } = validateCompactSessionOptions(options);
+    const { scope, state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    this.core.assertSessionWritable(stored);
+    const invocationOwner = this.core.commands.slashCommandInvocationContext.getStore();
+    if (invocationOwner?.sessionKey === this.core.commands.slashCommandSessionKey(state.storageKey, sessionId)) {
+      throw this.core.trustInternalError(new FlexHarnessSlashCommandReentryError(sessionId));
+    }
+    this.core.assertStateAcceptingWork(state);
+    if (!this.core.agentSessionPolicy.contextCompactor) {
+      throw new FlexHarnessSlashCommandUnavailableError(
+        'compact',
+        'No context compactor is configured.',
+      );
+    }
+    this.core.commands.requireSessionAvailableForSlashCommand(state, stored, 'compact');
+    await this.core.commands.trackSlashCommandExecution(
+      scopeId,
+      state,
+      sessionId,
+      'operation',
+      undefined,
+      async (signal) => {
+        await this.core.reversions.commitRevertedBranch(state, stored, scopeId, scope.scope);
+        await this.compactStoredSession(scopeId, scope.scope, state, stored, modelHint, signal);
+      },
+    );
+  }
+
+  public async compactStoredSession(
+    scopeId: string,
+    scope: TScope,
+    state: IStorageState,
+    stored: IStoredSessionState,
+    modelHint: string | undefined,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    try {
+      await this.withCompactorContext(
+        this.createCompactorContext(
+          scopeId,
+          scope,
+          state.storageKey,
+          stored.session.sessionId,
+          modelHint,
+        ),
+        () => stored.agentSession.compact(signal === undefined ? {} : { abort: signal }),
+      );
+    } catch (error) {
+      throw this.core.projectOperationError(
+        error,
+        'agentSession',
+        scopeId,
+        stored.session.sessionId,
+        'compaction',
+      );
+    }
+  }
+
+  public abortCompactorLifecycle(stored: IStoredSessionState, reason: FlexHarnessAbortError): void {
+    if (!stored.compactorLifecycleController.signal.aborted) {
+      stored.compactorLifecycleController.abort(reason);
+    }
+  }
+
+  public createCompactorContext(
+    scopeId: string,
+    scope: TScope,
+    storageKey: string,
+    sessionId: string,
+    modelHint?: string,
+  ): ICompactorInvocation<TScope> {
+    return Object.freeze({
+      scopeId,
+      scope,
+      storageKey,
+      sessionId,
+      ...(modelHint === undefined ? {} : { modelHint }),
+    });
+  }
+
+  /**
+   * The model the compacted work was dispatched on: the resolved model of the run whose context
+   * overflowed, or the model hint a manual compaction was requested with. Retention states none.
+   */
+  public compactionModel(
+    state: IStorageState,
+    sessionId: string,
+    ambientContext: IFlexAgentContextInvocation<TScope>,
+    reason: IFlexAgentContextCompactionOptions['reason'],
+    modelHint: string | undefined,
+  ): Pick<IFlexAgentContextCompactionOptions<TScope>, 'resolvedModel' | 'modelHint'> {
+    if (reason === 'manual') return modelHint === undefined ? {} : { modelHint };
+    if (reason !== 'context-overflow' && reason !== 'context-budget') return {};
+    const run = state.activeRuns.get(sessionId);
+    if (
+      !run
+      || (ambientContext !== run.originCompactorContext && ambientContext !== run.deferredCompactorContext)
+    ) {
+      throw new Error('Context-overflow compaction is missing its exact FlexHarness run.');
+    }
+    const resolved = run.modelResolution;
+    if (!resolved) throw new Error('Context-overflow compaction ran before its run resolved a model.');
+    return {
+      resolvedModel: Object.freeze({ ...resolved, identity: Object.freeze({ ...resolved.identity }) }),
+    };
+  }
+
+  public withCompactorContext<TResult>(
+    context: IFlexAgentContextInvocation<unknown>,
+    operation: () => TResult,
+  ): TResult {
+    return this.compactorInvocationContext.run(
+      context as IFlexAgentContextInvocation<TScope>,
+      operation,
+    );
+  }
+
+  public createRunCompactorContext(run: IActiveRun): IFlexAgentContextInvocation<TScope> {
+    return run.originCompactorContext as IFlexAgentContextInvocation<TScope>;
+  }
+
+  public effectiveRunCompactorContext(run: IActiveRun): IFlexAgentContextInvocation<TScope> {
+    return (run.deferredCompactorContext ?? run.originCompactorContext) as IFlexAgentContextInvocation<TScope>;
+  }
+
+  public withRunCompactorContext<TResult>(run: IActiveRun, operation: () => TResult): TResult {
+    return this.withCompactorContext(this.effectiveRunCompactorContext(run), operation);
+  }
+}

package/ts/classes.flexharness.configurations.ts

@@ -0,0 +1,167 @@
+import { FlexHarnessAbortError, FlexHarnessValidationError } from './errors.js';
+import {
+  normalizeAllowedTools,
+  normalizeSlashCommands,
+  normalizeSubagents,
+} from './utils.harnessoptions.js';
+import type {
+  IStoredSessionState,
+  IStorageState,
+  IResolvedSessionConfiguration,
+  ISessionConfigurationOwner,
+} from './interfaces.flexharness.js';
+import { requireSessionGeneration } from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** Session configurations from the session configuration resolver, and their owners. */
+export class FlexHarnessSessionConfigurations<TScope> {
+  public readonly sessionConfigurations = new Map<string, ISessionConfigurationOwner<TScope>>();
+
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async resolveSessionConfiguration(
+    scopeId: string,
+    scope: TScope,
+    state: IStorageState,
+    stored: IStoredSessionState,
+    signal?: AbortSignal,
+  ): Promise<IResolvedSessionConfiguration<TScope>> {
+    const configurationRef = stored.session.configurationRef;
+    if (configurationRef === undefined) {
+      return { subagents: this.core.subagents, slashCommands: this.core.slashCommands };
+    }
+    const sessionId = stored.session.sessionId;
+    const generation = requireSessionGeneration(stored.session);
+    const key = JSON.stringify([
+      state.storageKey,
+      sessionId,
+      generation.sessionGenerationId,
+      generation.sessionGenerationSequence,
+      configurationRef,
+    ]);
+    let owner = this.sessionConfigurations.get(key);
+    if (!owner) {
+      const controller = new AbortController();
+      const parent = stored.session.parentSessionId === undefined
+        ? undefined
+        : state.sessions.get(stored.session.parentSessionId);
+      if (stored.session.parentSessionId !== undefined && !parent) {
+        throw this.core.trustInternalError(new FlexHarnessAbortError('The session parent is no longer available.'));
+      }
+      const parentGeneration = parent === undefined ? undefined : requireSessionGeneration(parent.session);
+      const context = Object.freeze({
+        scopeId,
+        scope,
+        storageKey: state.storageKey,
+        sessionId,
+        ...generation,
+        configurationRef,
+        ...(parent === undefined ? {} : {
+          parentSessionId: parent.session.sessionId,
+          parentSessionGenerationId: parentGeneration!.sessionGenerationId,
+          parentSessionGenerationSequence: parentGeneration!.sessionGenerationSequence,
+        }),
+        ...(stored.session.agent === undefined ? {} : { agent: stored.session.agent }),
+        depth: stored.session.depth ?? 0,
+        signal: controller.signal,
+      });
+      let rejectAbort!: (reason: unknown) => void;
+      const aborted = new Promise<never>((_resolve, reject) => { rejectAbort = reject; });
+      const onAbort = () => rejectAbort(controller.signal.reason);
+      controller.signal.addEventListener('abort', onAbort, { once: true });
+      const resolved = Promise.resolve().then(() => {
+        if (!this.core.sessionConfigurationResolver) {
+          throw new Error('A sessionConfigurationResolver is required for bound sessions.');
+        }
+        return this.core.sessionConfigurationResolver.resolveSessionConfiguration(context);
+      });
+      const completion = Promise.race([resolved, aborted]).then((configuration) => {
+        controller.signal.throwIfAborted();
+        if (
+          state.lifecycle !== 'active'
+          || state.sessions.get(sessionId) !== stored
+          || stored.session.configurationRef !== configurationRef
+          || stored.session.sessionGenerationId !== generation.sessionGenerationId
+          || stored.session.sessionGenerationSequence !== generation.sessionGenerationSequence
+        ) {
+          throw this.core.trustInternalError(new FlexHarnessAbortError(
+            'The session configuration lost its session generation ownership.',
+          ));
+        }
+        if (
+          !configuration
+          || typeof configuration !== 'object'
+          || Array.isArray(configuration)
+          || ![Object.prototype, null].includes(Object.getPrototypeOf(configuration))
+          || Reflect.ownKeys(configuration).some((name) =>
+            typeof name !== 'string' || !['subagents', 'slashCommands', 'allowedTools', 'permissionPolicy'].includes(name))
+        ) throw new FlexHarnessValidationError('Resolved session configuration is invalid.');
+        if (configuration.permissionPolicy !== undefined && typeof configuration.permissionPolicy !== 'function') {
+          throw new FlexHarnessValidationError('Resolved session permissionPolicy must be a function.');
+        }
+        return Object.freeze({
+          subagents: normalizeSubagents(configuration.subagents),
+          slashCommands: normalizeSlashCommands(configuration.slashCommands),
+          allowedTools: normalizeAllowedTools(configuration.allowedTools),
+          permissionPolicy: configuration.permissionPolicy,
+        });
+      }).catch((error: unknown) => {
+        if (this.sessionConfigurations.get(key)?.completion === completion) {
+          this.sessionConfigurations.delete(key);
+        }
+        if (controller.signal.aborted) throw controller.signal.reason;
+        throw this.core.projectOperationError(
+          error,
+          'sessionConfigurationResolver',
+          scopeId,
+          sessionId,
+          'session-configuration',
+        );
+      }).finally(() => {
+        controller.signal.removeEventListener('abort', onAbort);
+        const current = this.sessionConfigurations.get(key);
+        if (current?.completion === completion) current.settled = true;
+      });
+      owner = { storageKey: state.storageKey, sessionId, controller, completion, settled: false, waiters: 0 };
+      this.sessionConfigurations.set(key, owner);
+    }
+    owner.waiters++;
+    let onConsumerAbort: (() => void) | undefined;
+    const consumerAbort = signal && new Promise<never>((_resolve, reject) => {
+      onConsumerAbort = () => reject(signal.reason ?? this.core.trustInternalError(
+        new FlexHarnessAbortError('Session configuration resolution was aborted.'),
+      ));
+      signal.addEventListener('abort', onConsumerAbort, { once: true });
+      if (signal.aborted) onConsumerAbort();
+    });
+    try {
+      return await (consumerAbort
+        ? Promise.race([owner.completion, consumerAbort])
+        : owner.completion);
+    } finally {
+      if (signal && onConsumerAbort) signal.removeEventListener('abort', onConsumerAbort);
+      owner.waiters--;
+      if (owner.waiters === 0 && !owner.settled && !owner.controller.signal.aborted) {
+        if (this.sessionConfigurations.get(key) === owner) this.sessionConfigurations.delete(key);
+        owner.controller.abort(this.core.trustInternalError(new FlexHarnessAbortError(
+          'Session configuration resolution has no active callers.',
+        )));
+      }
+    }
+  }
+
+  public abortSessionConfigurations(
+    storageKey: string,
+    reason: FlexHarnessAbortError,
+    sessionIds?: ReadonlySet<string>,
+  ): Promise<void> | undefined {
+    const owners = [...this.sessionConfigurations.entries()].filter(([, owner]) =>
+      owner.storageKey === storageKey && (sessionIds === undefined || sessionIds.has(owner.sessionId)));
+    if (owners.length === 0) return undefined;
+    for (const [key, owner] of owners) {
+      this.sessionConfigurations.delete(key);
+      if (!owner.controller.signal.aborted) owner.controller.abort(reason);
+    }
+    return Promise.allSettled(owners.map(([, owner]) => owner.completion)).then(() => undefined);
+  }
+}