@modelprofile.com/flexharness 10.23.0 → 10.24.1

package/ts/classes.flexharness.callbacks.ts

@@ -0,0 +1,352 @@
+import * as plugins from './plugins.js';
+import { FlexHarnessCallbackOverflowError } from './errors.js';
+import {
+  FLEX_TOOL_CATALOG_TOOL_NAMES,
+  type IFlexReasoningMessagePart,
+  type IFlexToolMessagePart,
+  type IFlexUsage,
+  type TFlexAgentToolCallUpdateEvent,
+  type TFlexAgentToolCallFinishEvent,
+  type TFlexMessagePart,
+} from './interfaces.js';
+import { normalizeJsonValue } from './utils.json.js';
+import { jsonBytes } from './utils.transfer.js';
+import {
+  observeSessionMetricsCall,
+  settleSessionMetricsOperation,
+  type ISessionMetricsOperation,
+} from './utils.sessionmetrics.js';
+import type { IStoredSessionState, IStorageState, IActiveRun } from './interfaces.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** The model stream callbacks of a run: text, reasoning, tool, retry and usage events. */
+export class FlexHarnessRunCallbacks<TScope> {
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public onTextDelta(state: IStorageState, sessionId: string, delta: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || !delta) return;
+    const lastPart = run.callbackParts.at(-1);
+    const created = lastPart?.type !== 'text';
+    const part = lastPart?.type === 'text'
+      ? lastPart
+      : { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: '' };
+    const accounting = this.textAppendAccounting(run, part, delta, created);
+    if (!accounting) return;
+    if (!this.reserveCallbackCapacity(
+      run,
+      created ? 2 : 1,
+      accounting.textUtf8Bytes - accounting.baseTextUtf8Bytes,
+      created ? 1 : 0,
+    )) return;
+    if (created) {
+      run.callbackParts.push(part);
+      run.partTextUtf8Bytes.set(part.partId, 0);
+      this.core.emitPartEvent(run, 'part.started', part);
+    }
+    part.text += delta;
+    run.partTextUtf8Bytes.set(part.partId, accounting.textUtf8Bytes);
+    this.core.emitPartDeltaEvent(run, part, delta, accounting);
+  }
+
+  public onReasoningStart(state: IStorageState, sessionId: string, id: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || run.reasoningPartIds.has(id)) return;
+    if (!this.reserveCallbackCapacity(run, 1, 0, 1)) return;
+    const part: IFlexReasoningMessagePart = {
+      partId: plugins.crypto.randomUUID(),
+      type: 'reasoning',
+      text: '',
+      status: 'running',
+      startedAt: new Date().toISOString(),
+    };
+    run.reasoningPartIds.set(id, part.partId);
+    run.callbackParts.push(part);
+    run.partTextUtf8Bytes.set(part.partId, 0);
+    this.core.emitPartEvent(run, 'part.started', part);
+  }
+
+  public onReasoningDelta(state: IStorageState, sessionId: string, id: string, delta: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || !delta) return;
+    if (!run.reasoningPartIds.has(id)) this.onReasoningStart(state, sessionId, id);
+    const partId = run.reasoningPartIds.get(id);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'reasoning');
+    if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
+    const accounting = this.textAppendAccounting(run, part, delta);
+    if (!accounting) return;
+    if (!this.reserveCallbackCapacity(
+      run,
+      1,
+      accounting.textUtf8Bytes - accounting.baseTextUtf8Bytes,
+      0,
+    )) return;
+    part.text += delta;
+    run.partTextUtf8Bytes.set(part.partId, accounting.textUtf8Bytes);
+    this.core.emitPartDeltaEvent(run, part, delta, accounting);
+  }
+
+  public onReasoningEnd(state: IStorageState, sessionId: string, id: string, text: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    if (!run.reasoningPartIds.has(id)) this.onReasoningStart(state, sessionId, id);
+    const partId = run.reasoningPartIds.get(id);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'reasoning');
+    if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
+    const missingText = part.text ? '' : text;
+    const missingTextUtf8Bytes = Buffer.byteLength(missingText, 'utf8');
+    if (!this.reserveCallbackCapacity(run, 1, missingTextUtf8Bytes, 0)) return;
+    if (missingText) {
+      part.text = missingText;
+      run.partTextUtf8Bytes.set(part.partId, missingTextUtf8Bytes);
+    }
+    part.status = 'completed';
+    part.completedAt = new Date().toISOString();
+    this.core.emitPartEvent(run, 'part.completed', part);
+  }
+
+  private textAppendAccounting(
+    run: IActiveRun,
+    part: Extract<TFlexMessagePart, { type: 'text' | 'reasoning' }>,
+    delta: string,
+    created = false,
+  ): { baseTextUtf8Bytes: number; textUtf8Bytes: number } | undefined {
+    const baseTextUtf8Bytes = created ? 0 : run.partTextUtf8Bytes.get(part.partId);
+    if (baseTextUtf8Bytes === undefined) {
+      throw new Error('Flex part text byte accounting is unavailable.');
+    }
+    const trailingCodeUnit = part.text.charCodeAt(part.text.length - 1);
+    const leadingCodeUnit = delta.charCodeAt(0);
+    const joinsSurrogatePair = trailingCodeUnit >= 0xD800
+      && trailingCodeUnit <= 0xDBFF
+      && leadingCodeUnit >= 0xDC00
+      && leadingCodeUnit <= 0xDFFF;
+    const textUtf8Bytes = baseTextUtf8Bytes
+      + Buffer.byteLength(delta, 'utf8')
+      - (joinsSurrogatePair ? 2 : 0);
+    if (!Number.isSafeInteger(textUtf8Bytes)) {
+      this.failCallback(run, this.core.trustInternalError(new FlexHarnessCallbackOverflowError(
+        'Callback text byte accounting exceeded the safe integer range.',
+      )));
+      return undefined;
+    }
+    return { baseTextUtf8Bytes, textUtf8Bytes };
+  }
+
+  public onToolStart(
+    state: IStorageState,
+    sessionId: string,
+    event: { toolCallId: string; toolName: string; input: unknown; parentToolCallId?: string },
+  ): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || run.toolPartIds.has(event.toolCallId)) return;
+    try {
+      // An execute call is the call of the catalog method it names.
+      const target = event.toolName === FLEX_TOOL_CATALOG_TOOL_NAMES.execute
+        ? run.toolCatalog?.callTarget(event.input)
+        : undefined;
+      const input = normalizeJsonValue(target ? target.params : event.input, this.core.toolOutputLimits);
+      if (!this.reserveCallbackCapacity(run, 1, jsonBytes(input), 1)) return;
+      const part: IFlexToolMessagePart = {
+        partId: plugins.crypto.randomUUID(),
+        type: 'tool',
+        toolCallId: this.core.boundedIdentifier(event.toolCallId, 'toolCallId'),
+        toolName: this.core.boundedIdentifier(target ? target.method : event.toolName, 'toolName'),
+        status: 'running',
+        input,
+        ...(event.parentToolCallId === undefined
+          ? {}
+          : { parentToolCallId: this.core.boundedIdentifier(event.parentToolCallId, 'parentToolCallId') }),
+        startedAt: new Date().toISOString(),
+      };
+      run.toolPartIds.set(event.toolCallId, part.partId);
+      run.callbackParts.push(part);
+      this.core.emitPartEvent(run, 'part.started', part);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  public onToolFinish(
+    state: IStorageState,
+    sessionId: string,
+    event: TFlexAgentToolCallFinishEvent,
+  ): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    if (!run.toolPartIds.has(event.toolCallId)) this.onToolStart(state, sessionId, event);
+    const partId = run.toolPartIds.get(event.toolCallId);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
+    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    try {
+      const trustedExecutionError = run.trustedToolExecutionErrors.get(event.toolCallId);
+      run.trustedToolExecutionErrors.delete(event.toolCallId);
+      const output = event.success ? normalizeJsonValue(event.output, this.core.toolOutputLimits) : undefined;
+      const projectedError = event.success
+        ? undefined
+        : this.core.projectExternalError(run, trustedExecutionError ?? event.error, 'toolCallback');
+      const bytes = event.success ? jsonBytes(output) : Buffer.byteLength(projectedError!.message);
+      if (!this.reserveCallbackCapacity(run, 1, bytes - (part.output === undefined ? 0 : jsonBytes(part.output)), 0)) return;
+      if (event.success) {
+        part.status = 'completed';
+        part.output = output!;
+      } else {
+        part.status = 'failed';
+        delete part.output;
+        part.error = projectedError!.message;
+      }
+      const original = run.deduplicatedToolCalls.get(event.toolCallId);
+      if (original !== undefined) {
+        part.deduplicatedFrom = this.core.boundedIdentifier(original, 'deduplicatedFrom');
+      }
+      part.completedAt = new Date().toISOString();
+      this.core.emitPartEvent(run, 'part.completed', part);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  public onToolUpdate(
+    state: IStorageState,
+    sessionId: string,
+    event: TFlexAgentToolCallUpdateEvent,
+  ): void {
+    let run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    if (!run.toolPartIds.has(event.toolCallId)) {
+      this.onToolStart(state, sessionId, event);
+      run = this.callbackRun(state, sessionId);
+      if (!run) return;
+    }
+    const partId = run.toolPartIds.get(event.toolCallId);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
+    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    try {
+      const output = normalizeJsonValue(event.output, this.core.toolOutputLimits);
+      if (!this.reserveCallbackCapacity(run, 1, jsonBytes(output) - (part.output === undefined ? 0 : jsonBytes(part.output)), 0)) return;
+      part.output = output;
+      this.core.emitPartEvent(run, 'part.updated', part);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  public onRetry(state: IStorageState, sessionId: string, retry: plugins.IAgentRetryEvent): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run || !this.reserveCallbackCapacity(run, 1, 0, 0)) return;
+    this.core.emitEvent(run.scopeId, run.stored.session, {
+      type: 'run.retrying',
+      runId: run.runId,
+      attempt: retry.attempt,
+      maxAttempts: retry.maxAttempts,
+      delayMs: retry.delayMs,
+      reason: retry.reason,
+    });
+  }
+
+  /**
+   * Emits the usage of every model call and adds reported usage to its run. A run executes a
+   * transactional generation, and `AgentSession.generate()` settles a transactional generation only
+   * after it has reported each of its model calls, also when it is aborted. `executeRun()` awaits
+   * that settlement before it builds the terminal, so the run is still active for each of its
+   * events: they all reach `run.usage` and precede its `run.finished`. The events bypass the
+   * callback limits and a failed callback: their number is bounded by the run's model calls, and
+   * the usage of a run that exhausted its callback budget or failed in a callback must not be lost.
+   */
+  public onModelCallUsage(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    event: plugins.TAgentModelCallUsageEvent,
+  ): void {
+    try {
+      const { source, generationId, ...call } = event;
+      const sessionId = stored.session.sessionId;
+      const activeRun = state.activeRuns.get(sessionId);
+      const run = generationId !== undefined && activeRun?.runId === generationId ? activeRun : undefined;
+      const operation = source === 'compaction' ? stored.metricsCompaction : run?.metricsOperation;
+      if (!operation) throw new Error('Model call usage has no owning metrics operation.');
+      observeSessionMetricsCall(operation, call);
+      let scopeId = run?.scopeId;
+      if (scopeId === undefined) {
+        const ambientContext = this.core.compaction.compactorInvocationContext.getStore();
+        const invocationContext = ambientContext
+          ? this.core.compaction.deferredCompactorContexts.get(ambientContext) ?? ambientContext
+          : undefined;
+        if (
+          !invocationContext
+          || invocationContext.storageKey !== state.storageKey
+          || invocationContext.sessionId !== sessionId
+        ) {
+          throw new Error('Model call usage is missing its exact FlexHarness invocation context.');
+        }
+        scopeId = invocationContext.scopeId;
+      }
+      if (run && call.status === 'reported') {
+        for (const key of Object.keys(run.usage) as (keyof IFlexUsage)[]) run.usage[key] += call.usage[key];
+      }
+      this.core.emitEvent(scopeId, stored.session, {
+        type: 'model.usage',
+        ...(generationId === undefined ? {} : { runId: generationId }),
+        source,
+        ...call,
+      });
+    } catch (error) {
+      // AgentSession isolates the entire callback, including event/context failures. Join it later.
+      stored.metricsFailure ??= error;
+      throw error;
+    }
+  }
+
+  public async settleMetricsOperation(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    operation: ISessionMetricsOperation,
+  ): Promise<void> {
+    try {
+      if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
+      await this.core.mutateProjection(state, stored, () => settleSessionMetricsOperation(stored.metrics, operation), true);
+    } catch (error) {
+      stored.metricsFailure ??= error;
+      // Never allow a later operation to overwrite a marker whose spend was not durably joined.
+      state.lifecycle = 'fenced';
+      throw error;
+    }
+  }
+
+  private callbackRun(state: IStorageState, sessionId: string): IActiveRun | undefined {
+    const run = state.activeRuns.get(sessionId);
+    return !run || run.callbacksClosed || run.callbackError ? undefined : run;
+  }
+
+  public reserveCallbackCapacity(
+    run: IActiveRun,
+    eventCount: number,
+    outputBytes: number,
+    partCount: number,
+  ): boolean {
+    const nextEvents = run.callbackEventCount + eventCount;
+    const nextOutputBytes = run.callbackOutputBytes + outputBytes;
+    const nextParts = run.callbackParts.length + partCount;
+    if (
+      !Number.isSafeInteger(nextEvents)
+      || !Number.isSafeInteger(nextOutputBytes)
+      || !Number.isSafeInteger(nextParts)
+      || nextEvents > this.core.callbackLimits.maxEvents
+      || nextOutputBytes > this.core.callbackLimits.maxOutputBytes
+      || nextParts > this.core.callbackLimits.maxParts
+    ) {
+      this.failCallback(run, this.core.trustInternalError(new FlexHarnessCallbackOverflowError(
+        `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
+      )));
+      return false;
+    }
+    run.callbackEventCount = nextEvents;
+    run.callbackOutputBytes = nextOutputBytes;
+    return true;
+  }
+
+  private failCallback(run: IActiveRun, error: Error): void {
+    run.callbackError ??= error;
+    this.core.runs.abortRunInternally(run, error);
+  }
+}

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);
+  }
+}