@modelprofile.com/flexharness 10.23.0 → 10.24.1

package/ts/classes.flexharness.permissions.ts

@@ -0,0 +1,535 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessNotFoundError,
+  FlexHarnessPermissionRejectedError,
+  FlexHarnessPermissionStateError,
+  FlexHarnessStoreConflictError,
+  FlexHarnessStoreCommitUncertainError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import type {
+  IFlexAgentContextInvocation,
+  IFlexPermissionRequest,
+  IFlexPermissionRequestInput,
+  IFlexPermissionSnapshot,
+  IFlexSessionPermissionPolicyContext,
+  TFlexPermissionDecision,
+  TJsonValue,
+} from './interfaces.js';
+import { cloneSerializable, normalizeJsonValue } from './utils.json.js';
+import { maxTransferMetadataBytes, publicSnapshot, truncateUtf8 } from './utils.transfer.js';
+import { validateIdentifier } from './utils.validation.js';
+import type {
+  IStoredSessionState,
+  IStorageState,
+  IActiveRun,
+  IPendingPermission,
+} from './interfaces.flexharness.js';
+import { requireSessionGeneration, combineErrors } from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** Permission requests and responses, and the permission policy of sessions. */
+export class FlexHarnessPermissions<TScope> {
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async listPendingPermissions(
+    scopeId: string,
+    sessionId?: string,
+  ): Promise<IFlexPermissionRequest[]> {
+    const { state } = await this.core.resolveState(scopeId);
+    await state.scopeQueue;
+    this.core.assertStateAcceptingWork(state);
+    return publicSnapshot([...state.pendingPermissions.values()]
+      .map((pending) => pending.request)
+      .filter((request) => !sessionId || request.sessionId === sessionId)
+      .sort((left, right) => left.createdAt.localeCompare(right.createdAt)));
+  }
+
+  public async respondToPermission(
+    scopeId: string,
+    sessionId: string,
+    permissionId: string,
+    decision: TFlexPermissionDecision,
+  ): Promise<void> {
+    validateIdentifier(permissionId, 'permissionId');
+    const { scope, state } = await this.core.resolveState(scopeId);
+    const pending = state.pendingPermissions.get(permissionId);
+    if (!pending || pending.request.sessionId !== sessionId) {
+      throw new FlexHarnessNotFoundError('Permission', permissionId);
+    }
+    const context = this.core.compaction.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId);
+    const response = pending.responseQueue.then(() => this.core.compaction.withCompactorContext(
+      context,
+      () => this.applyPermissionResponse(state, pending, decision, context),
+    ));
+    pending.responseQueue = response.then(() => undefined, () => undefined);
+    return response;
+  }
+
+  public async requestPermission(
+    state: IStorageState,
+    run: IActiveRun,
+    input: IFlexPermissionRequestInput,
+    exactMetadata?: TJsonValue,
+  ): Promise<void> {
+    validateIdentifier(input.kind, 'permission kind');
+    validateIdentifier(input.description, 'permission description');
+    if (input.rememberKey !== undefined) validateIdentifier(input.rememberKey, 'rememberKey');
+    if (input.toolCallId !== undefined) validateIdentifier(input.toolCallId, 'toolCallId');
+    run.controller.signal.throwIfAborted();
+    await run.stored.permissionQueue;
+    run.controller.signal.throwIfAborted();
+    if (state.activeRuns.get(run.sessionId) !== run || run.callbacksClosed) {
+      throw new FlexHarnessPermissionStateError(`Run "${run.runId}" no longer accepts permission requests.`);
+    }
+    if (!run.permissionPolicy && input.rememberKey && run.stored.rememberedPermissionKeys.has(input.rememberKey)) {
+      return;
+    }
+    const candidate: IFlexPermissionRequest = {
+      permissionId: plugins.crypto.randomUUID(),
+      scopeId: run.scopeId,
+      sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
+      runId: run.runId,
+      kind: input.kind,
+      description: truncateUtf8(input.description, maxTransferMetadataBytes),
+      ...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
+      ...(input.rememberKey ? { rememberKey: input.rememberKey } : {}),
+      ...(exactMetadata !== undefined
+        ? { metadata: cloneSerializable(exactMetadata) }
+        : input.metadata === undefined
+          ? {}
+          : { metadata: normalizeJsonValue(input.metadata, this.core.toolOutputLimits) }),
+      createdAt: new Date().toISOString(),
+    };
+    const policyDecision = run.permissionPolicy
+      ? await this.decideSessionPermissionPolicy(state, run, candidate)
+      : 'inherit';
+    if (policyDecision === 'allow' || policyDecision === 'deny') {
+      this.core.emitEvent(run.scopeId, run.stored.session, {
+        type: 'permission.resolved',
+        runId: run.runId,
+        request: publicSnapshot(candidate),
+        decision: policyDecision === 'allow' ? 'once' : 'reject',
+        origin: 'policy',
+      });
+      if (policyDecision === 'deny') {
+        const rejection = this.core.trustInternalError(
+          new FlexHarnessPermissionRejectedError(candidate.permissionId),
+        );
+        this.core.runs.abortRunInternally(run, rejection);
+        throw rejection;
+      }
+      return;
+    }
+    if (policyDecision === 'inherit'
+      && input.rememberKey && run.stored.rememberedPermissionKeys.has(input.rememberKey)) return;
+    const request: IFlexPermissionRequest = { ...candidate };
+    if (policyDecision === 'ask') {
+      delete request.rememberKey;
+      request.requiresExplicitResponse = true;
+    }
+    let resolvePermission!: () => void;
+    let rejectPermission!: (error: unknown) => void;
+    const promise = new Promise<void>((resolve, reject) => {
+      resolvePermission = resolve;
+      rejectPermission = reject;
+    });
+    void promise.catch(() => undefined);
+    const abortListener = () => {
+      const pending = state.pendingPermissions.get(request.permissionId);
+      if (pending) this.rejectPending(state, pending, run.controller.signal.reason);
+    };
+    const pending: IPendingPermission = {
+      request,
+      run,
+      resolve: resolvePermission,
+      reject: rejectPermission,
+      settled: false,
+      responding: false,
+      responseQueue: Promise.resolve(),
+      abortListener,
+    };
+    const closePublication = this.core.openPublication(state, run.sessionId);
+    try {
+      state.pendingPermissions.set(request.permissionId, pending);
+      run.pendingPermissionIds.add(request.permissionId);
+      run.controller.signal.addEventListener('abort', abortListener, { once: true });
+      try {
+        await this.core.mutateScope(state, () => {
+          if (state.sessions.get(run.sessionId) !== run.stored) {
+            throw new FlexHarnessAbortError('The session was deleted while permission was pending.');
+          }
+          run.stored.session.status = 'waiting_permission';
+          run.stored.session.activity.status = 'waiting_permission';
+          run.stored.session.updatedAt = new Date().toISOString();
+        }, true);
+      } catch (error) {
+        this.forceRejectPending(state, pending, this.core.projectExternalError(run, error, 'persistence'));
+        return promise;
+      }
+      if (!pending.settled) {
+        this.core.emitEvent(run.scopeId, run.stored.session, {
+          type: 'permission.requested',
+          runId: run.runId,
+          request: publicSnapshot(request),
+        });
+      }
+    } finally {
+      closePublication();
+    }
+    return promise;
+  }
+
+  private async decideSessionPermissionPolicy(
+    state: IStorageState,
+    run: IActiveRun,
+    request: IFlexPermissionRequest,
+  ): Promise<'inherit' | 'allow' | 'ask' | 'deny'> {
+    const policy = run.permissionPolicy!;
+    const signal = run.controller.signal;
+    const context: Readonly<IFlexSessionPermissionPolicyContext<unknown>> = Object.freeze({
+      scopeId: run.scopeId,
+      scope: run.scope,
+      storageKey: state.storageKey,
+      sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
+      runId: run.runId,
+      configurationRef: run.stored.session.configurationRef!,
+      ...(run.stored.session.agent === undefined ? {} : { agent: run.stored.session.agent }),
+      request: publicSnapshot(request),
+      signal,
+    });
+    let onAbort!: () => void;
+    const aborted = new Promise<never>((_resolve, reject) => {
+      onAbort = () => reject(signal.reason ?? this.core.trustInternalError(new FlexHarnessAbortError()));
+    });
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) onAbort();
+    let decision: unknown;
+    try {
+      decision = await Promise.race([
+        Promise.resolve().then(() => {
+          signal.throwIfAborted();
+          return policy(context);
+        }),
+        aborted,
+      ]);
+      if (!['inherit', 'allow', 'ask', 'deny'].includes(decision as string)) {
+        throw new FlexHarnessValidationError('Session permissionPolicy returned an invalid decision.');
+      }
+    } catch (error) {
+      if (signal.aborted) throw signal.reason;
+      const projected = this.core.projectExternalError(run, error, 'permissionPolicy');
+      this.core.runs.abortRunInternally(run, projected);
+      throw projected;
+    } finally {
+      signal.removeEventListener('abort', onAbort);
+    }
+    signal.throwIfAborted();
+    const generation = requireSessionGeneration(run.stored.session);
+    if (
+      state.lifecycle !== 'active'
+      || state.activeRuns.get(run.sessionId) !== run
+      || state.sessions.get(run.sessionId) !== run.stored
+      || run.callbacksClosed
+      || generation.sessionGenerationId !== request.sessionGenerationId
+      || generation.sessionGenerationSequence !== request.sessionGenerationSequence
+    ) {
+      const ownershipError = this.core.trustInternalError(new FlexHarnessAbortError(
+        'Permission policy lost its exact run ownership.',
+      ));
+      this.core.runs.abortRunInternally(run, ownershipError);
+      throw ownershipError;
+    }
+    return decision as 'inherit' | 'allow' | 'ask' | 'deny';
+  }
+
+  private async applyPermissionResponse(
+    state: IStorageState,
+    pending: IPendingPermission,
+    decision: TFlexPermissionDecision,
+    context: IFlexAgentContextInvocation<TScope>,
+  ): Promise<void> {
+    if (pending.settled) {
+      throw new FlexHarnessPermissionStateError(`Permission "${pending.request.permissionId}" has already been resolved.`);
+    }
+    if (!['once', 'always', 'reject'].includes(decision)) {
+      throw new FlexHarnessPermissionStateError(`Unknown permission decision "${decision}".`);
+    }
+    if (decision === 'always' && !pending.request.rememberKey) {
+      throw new FlexHarnessPermissionStateError('The always decision requires rememberKey.');
+    }
+    const stored = pending.run.stored;
+    const rememberKey = pending.request.rememberKey;
+    let addedRememberKey = false;
+    pending.responding = true;
+    try {
+      if (decision === 'always' && rememberKey) {
+        await this.mutatePermissions(state, stored, () => {
+          addedRememberKey = !stored.rememberedPermissionKeys.has(rememberKey);
+          stored.rememberedPermissionKeys.add(rememberKey);
+        });
+      }
+      await this.core.mutateScope(state, () => {
+        if (state.sessions.get(pending.request.sessionId) !== stored) {
+          throw new FlexHarnessAbortError('The session was deleted while permission was resolving.');
+        }
+        const hasOtherPending = [...state.pendingPermissions.values()].some((entry) =>
+          entry !== pending && !entry.settled && entry.request.sessionId === pending.request.sessionId);
+        stored.session.status = hasOtherPending ? 'waiting_permission' : 'running';
+        stored.session.activity.status = hasOtherPending ? 'waiting_permission' : 'running';
+        stored.session.updatedAt = new Date().toISOString();
+      }, true);
+    } catch (error) {
+      pending.responding = false;
+      const projected = this.core.projectExternalError(pending.run, error, 'persistence');
+      const rollbackErrors = await this.rollbackRememberedGrant(
+        state,
+        pending,
+        addedRememberKey,
+        rememberKey,
+      );
+      if (
+        pending.abortReason === undefined
+        && state.sessions.get(pending.request.sessionId) === stored
+        && stored.session.status !== 'waiting_permission'
+      ) {
+        try {
+          await this.core.mutateScope(state, () => {
+            stored.session.status = 'waiting_permission';
+            stored.session.activity.status = 'waiting_permission';
+            stored.session.updatedAt = new Date().toISOString();
+          }, true);
+        } catch (rollbackError) {
+          rollbackErrors.push(this.core.projectExternalError(pending.run, rollbackError, 'persistence'));
+        }
+      }
+      if (pending.abortReason !== undefined) {
+        this.forceRejectPending(state, pending, pending.abortReason);
+      }
+      if (rollbackErrors.length > 0 || state.lifecycle === 'fenced') {
+        if (!pending.settled) this.forceRejectPending(state, pending, projected);
+        const combined = combineErrors([
+          ...(pending.abortReason === undefined ? [] : [pending.abortReason]),
+          projected,
+          ...rollbackErrors,
+        ]);
+        await this.core.lifecycle.fenceNamespace(state, pending.run, combined);
+        throw combined;
+      }
+      if (pending.abortReason !== undefined) throw pending.abortReason;
+      throw projected;
+    }
+    if (pending.abortReason !== undefined) {
+      const rollbackErrors = await this.rollbackRememberedGrant(state, pending, addedRememberKey, rememberKey);
+      pending.responding = false;
+      this.forceRejectPending(state, pending, pending.abortReason);
+      if (rollbackErrors.length > 0) {
+        const combined = combineErrors([pending.abortReason, ...rollbackErrors]);
+        await this.core.lifecycle.fenceNamespace(state, pending.run, combined);
+        throw combined;
+      }
+      throw pending.abortReason;
+    }
+    pending.settled = true;
+    pending.responding = false;
+    state.pendingPermissions.delete(pending.request.permissionId);
+    pending.run.pendingPermissionIds.delete(pending.request.permissionId);
+    pending.run.controller.signal.removeEventListener('abort', pending.abortListener);
+    this.core.emitEvent(pending.request.scopeId, pending.run.stored.session, {
+      type: 'permission.resolved',
+      runId: pending.request.runId,
+      request: publicSnapshot(pending.request),
+      decision,
+    });
+    if (decision === 'reject') {
+      const rejection = this.core.trustInternalError(
+        new FlexHarnessPermissionRejectedError(pending.request.permissionId),
+      );
+      this.core.runs.abortRunInternally(pending.run, rejection, context);
+      pending.reject(rejection);
+    } else {
+      pending.resolve();
+    }
+  }
+
+  private async rollbackRememberedGrant(
+    state: IStorageState,
+    pending: IPendingPermission,
+    added: boolean,
+    rememberKey?: string,
+  ): Promise<unknown[]> {
+    if (
+      !added
+      || !rememberKey
+      || !pending.run.stored.rememberedPermissionKeys.has(rememberKey)
+    ) return [];
+    try {
+      await this.mutatePermissions(state, pending.run.stored, () => {
+        pending.run.stored.rememberedPermissionKeys.delete(rememberKey);
+      }, true);
+      return [];
+    } catch (error) {
+      const initialError = this.core.projectExternalError(pending.run, error, 'persistence');
+      try {
+        await this.reconcileRememberedPermissionRemoval(
+          pending.run.stored,
+          state.storageKey,
+          rememberKey,
+        );
+        return [];
+      } catch (recoveryError) {
+        return [initialError, this.core.projectExternalError(pending.run, recoveryError, 'persistence')];
+      }
+    }
+  }
+
+  private async reconcileRememberedPermissionRemoval(
+    stored: IStoredSessionState,
+    storageKey: string,
+    rememberKey: string,
+  ): Promise<void> {
+    const operation = stored.permissionQueue.then(async () => {
+      let lastError: unknown;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          const current = await this.core.stores.permissions.load(storageKey, stored.session.sessionId);
+          if (!current || !current.rememberedPermissionKeys.includes(rememberKey)) {
+            stored.rememberedPermissionKeys = new Set(current?.rememberedPermissionKeys ?? []);
+            stored.permissionRevision = current?.revision ?? 0;
+            return;
+          }
+          const snapshot = {
+            ...current,
+            revision: current.revision + 1,
+            rememberedPermissionKeys: current.rememberedPermissionKeys.filter(
+              (entry) => entry !== rememberKey,
+            ),
+          };
+          await this.core.stores.permissions.save(
+            storageKey,
+            stored.session.sessionId,
+            snapshot,
+            current.revision,
+          );
+          stored.rememberedPermissionKeys = new Set(snapshot.rememberedPermissionKeys);
+          stored.permissionRevision = snapshot.revision;
+          return;
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      throw lastError ?? new Error('Remembered permission rollback could not be reconciled.');
+    });
+    stored.permissionQueue = operation.then(() => undefined, () => undefined);
+    await operation;
+  }
+
+  public rejectRunPermissions(state: IStorageState, run: IActiveRun, error: unknown): void {
+    for (const permissionId of [...run.pendingPermissionIds]) {
+      const pending = state.pendingPermissions.get(permissionId);
+      if (pending) this.rejectPending(state, pending, error);
+    }
+  }
+
+  public rejectPending(state: IStorageState, pending: IPendingPermission, error: unknown): void {
+    if (pending.settled) return;
+    if (pending.responding) {
+      pending.abortReason ??= error;
+      return;
+    }
+    this.forceRejectPending(state, pending, error);
+  }
+
+  private forceRejectPending(state: IStorageState, pending: IPendingPermission, error: unknown): void {
+    if (pending.settled) return;
+    pending.settled = true;
+    state.pendingPermissions.delete(pending.request.permissionId);
+    pending.run.pendingPermissionIds.delete(pending.request.permissionId);
+    pending.run.controller.signal.removeEventListener('abort', pending.abortListener);
+    pending.reject(error);
+  }
+
+  private mutatePermissions<TValue>(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    mutation: () => TValue,
+    _allowDuringDrain = false,
+  ): Promise<TValue> {
+    const operation = stored.permissionQueue.then(async () => {
+      const beforeRevision = stored.permissionRevision;
+      const beforeKeys = new Set(stored.rememberedPermissionKeys);
+      const beforeSnapshot = {
+        schemaVersion: 1 as const,
+        revision: beforeRevision,
+        rememberedPermissionKeys: [...beforeKeys].sort(),
+      };
+      const restore = () => {
+        stored.permissionRevision = beforeRevision;
+        stored.rememberedPermissionKeys = beforeKeys;
+      };
+      let result: TValue;
+      try {
+        result = mutation();
+      } catch (error) {
+        restore();
+        throw error;
+      }
+      const snapshot = {
+        schemaVersion: 1 as const,
+        revision: beforeRevision + 1,
+        rememberedPermissionKeys: [...stored.rememberedPermissionKeys].sort(),
+      };
+      try {
+        await this.core.stores.permissions.save(
+          state.storageKey,
+          stored.session.sessionId,
+          snapshot,
+          beforeRevision,
+        );
+        stored.permissionRevision = snapshot.revision;
+        return result;
+      } catch (error) {
+        if (error instanceof FlexHarnessStoreConflictError) {
+          restore();
+          throw error;
+        }
+        if (error instanceof FlexHarnessStoreCommitUncertainError) {
+          stored.permissionRevision = snapshot.revision;
+          state.lifecycle = 'fenced';
+          throw error;
+        }
+        let current: IFlexPermissionSnapshot | undefined;
+        let reconciliationError: unknown;
+        try {
+          current = await this.core.stores.permissions.load(
+            state.storageKey,
+            stored.session.sessionId,
+          );
+        } catch (loadError) {
+          reconciliationError = loadError;
+        }
+        if (current && JSON.stringify(current) === JSON.stringify(snapshot)) {
+          stored.permissionRevision = snapshot.revision;
+          throw error;
+        }
+        if (
+          (current === undefined && beforeRevision === 0)
+          || (current !== undefined && JSON.stringify(current) === JSON.stringify(beforeSnapshot))
+        ) {
+          restore();
+          throw error;
+        }
+        stored.permissionRevision = snapshot.revision;
+        state.lifecycle = 'fenced';
+        throw reconciliationError === undefined
+          ? error
+          : combineErrors([error, reconciliationError]);
+      }
+    });
+    stored.permissionQueue = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+}