@modelprofile.com/flexharness 9.6.1 → 9.8.0

package/ts/interfaces.ts

@@ -158,6 +158,8 @@ export interface IFlexSession {
   sessionId: string;
   sessionGenerationId?: string;
   sessionGenerationSequence?: number;
+  /** Opaque immutable configuration revision bound to this exact session generation. */
+  configurationRef?: string;
   title?: string;
   createdAt: string;
   updatedAt: string;
@@ -295,6 +297,7 @@ export const FLEX_SESSION_IMPORT_MAXIMUM_LIMITS = Object.freeze({
 export interface IFlexCreateSessionOptions {
   sessionId?: string;
   sessionGenerationId?: string;
+  configurationRef?: string;
   title?: string;
 }
 
@@ -529,9 +532,24 @@ export interface IFlexPermissionRequest
   sessionId: string;
   runId: string;
   createdAt: string;
+  /** A bound policy requires an explicit response and disallows remembered approval. */
+  requiresExplicitResponse?: true;
 }
 
 export type TFlexPermissionDecision = 'once' | 'always' | 'reject';
+export type TFlexSessionPermissionPolicyDecision = 'inherit' | 'allow' | 'ask' | 'deny';
+
+export interface IFlexSessionPermissionPolicyContext<TScope> extends IFlexSessionGeneration {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly runId: string;
+  readonly configurationRef: string;
+  readonly agent?: string;
+  readonly request: Readonly<IFlexPermissionRequest>;
+  readonly signal: AbortSignal;
+}
 
 export interface IFlexToolProviderContext<TScope> extends IFlexSessionGeneration {
   scopeId: string;
@@ -731,6 +749,39 @@ export interface IFlexSessionGeneration {
   sessionGenerationSequence: number;
 }
 
+export const FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES = 1024;
+
+export interface IFlexSessionConfigurationResolverContext<TScope> extends IFlexSessionGeneration {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly configurationRef: string;
+  readonly parentSessionId?: string;
+  readonly parentSessionGenerationId?: string;
+  readonly parentSessionGenerationSequence?: number;
+  readonly agent?: string;
+  readonly depth: number;
+  readonly signal: AbortSignal;
+}
+
+export interface IFlexResolvedSessionConfiguration<TScope> {
+  subagents?: readonly IFlexSubagentDefinition[];
+  slashCommands?: readonly TFlexSlashCommandRegistration<TScope>[];
+  /** Exact model-facing names permitted for this bound session; omitted means unrestricted. */
+  allowedTools?: readonly string[];
+  /** Evaluated for each request before a remembered grant can be reused. */
+  permissionPolicy?: (
+    context: IFlexSessionPermissionPolicyContext<TScope>,
+  ) => TFlexSessionPermissionPolicyDecision | Promise<TFlexSessionPermissionPolicyDecision>;
+}
+
+export interface IFlexSessionConfigurationResolver<TScope> {
+  resolveSessionConfiguration(
+    context: IFlexSessionConfigurationResolverContext<TScope>,
+  ): Promise<IFlexResolvedSessionConfiguration<TScope>> | IFlexResolvedSessionConfiguration<TScope>;
+}
+
 export interface IFlexSubagentProvenance {
   readonly parentSessionId: string;
   readonly parentSessionGenerationId: string;
@@ -1107,6 +1158,8 @@ export interface IFlexRedoSessionResult {
 
 export type TFlexExternalErrorSource =
   | 'modelResolver'
+  | 'sessionConfigurationResolver'
+  | 'permissionPolicy'
   | 'toolProvider'
   | 'delegatedRunAdmissionProvider'
   | 'toolExecution'
@@ -1237,6 +1290,8 @@ export interface IFlexSubagentDefinition {
   modelHint?: string;
   system?: string;
   maxSteps?: number;
+  /** Exact model-facing names permitted for this agent; omitted means unrestricted. */
+  allowedTools?: readonly string[];
 }
 
 export interface IFlexProjectManagementBuiltInToolsOptions {
@@ -1253,6 +1308,7 @@ export interface IFlexBuiltInToolsOptions {
 export interface IFlexHarnessOptions<TScope> {
   scopeResolver: IFlexScopeResolver<TScope>;
   modelResolver: IFlexModelResolver<TScope>;
+  sessionConfigurationResolver?: IFlexSessionConfigurationResolver<TScope>;
   toolProvider?: IFlexToolProvider<TScope>;
   resourceToolProviderResolver?: IFlexResourceToolProviderResolver<TScope>;
   executionContextProvider?: IFlexExecutionContextProvider<TScope>;
@@ -1388,6 +1444,8 @@ export interface IFlexPermissionResolvedEvent extends IFlexEventBase {
   readonly runId: string;
   readonly request: IFlexPermissionRequest;
   readonly decision: TFlexPermissionDecision;
+  /** Present when a bound policy resolved the request without making it pending. */
+  readonly origin?: 'policy';
 }
 
 export interface IFlexRunFinishedEvent extends IFlexEventBase {

package/ts/utils.harnessoptions.ts

@@ -54,14 +54,41 @@ export const maxSubagentNameBytes = 128;
 const maxSubagentDescriptionBytes = 2048;
 const maxSubagentModelHintBytes = 512;
 const maxSubagentSystemBytes = 64 * 1024;
+const maxAllowedToolNames = 128;
+const maxAllowedToolNameBytes = 512;
+const toolNameControlPattern = /[\u0000-\u001f\u007f-\u009f]/u;
+const toolNameUnpairedSurrogatePattern = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u;
 const maxSlashCommandRegistrations = 128;
 const maxSlashCommandDescriptionBytes = 2048;
 const maxSlashCommandTemplateBytes = FLEX_SLASH_COMMAND_MAX_INPUT_BYTES;
 const defaultReversionMaintenanceTimeoutMs = 30_000;
 const maximumReversionMaintenanceTimeoutMs = 30 * 60 * 1000;
 
+export function normalizeAllowedTools(
+  names: readonly string[] | undefined,
+  label = 'allowedTools',
+): readonly string[] | undefined {
+  if (names === undefined) return undefined;
+  if (!Array.isArray(names) || names.length > maxAllowedToolNames) {
+    throw new FlexHarnessValidationError(`${label} must be an array with at most ${maxAllowedToolNames} names.`);
+  }
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (let index = 0; index < names.length; index++) {
+    const name = names[index];
+    validateUtf8String(name, `${label}[${index}]`, maxAllowedToolNameBytes, true);
+    if (toolNameControlPattern.test(name) || toolNameUnpairedSurrogatePattern.test(name)) {
+      throw new FlexHarnessValidationError(`${label}[${index}] must be a well-formed name without control characters.`);
+    }
+    if (seen.has(name)) throw new FlexHarnessValidationError(`${label} contains duplicate name "${name}".`);
+    seen.add(name);
+    normalized.push(name);
+  }
+  return Object.freeze(normalized);
+}
+
 export function normalizeSubagents(
-  definitions: IFlexSubagentDefinition[] | undefined,
+  definitions: readonly IFlexSubagentDefinition[] | undefined,
 ): ReadonlyMap<string, Readonly<IFlexSubagentDefinition>> {
   if (definitions === undefined) return new Map();
   if (!Array.isArray(definitions) || definitions.length > maxSubagentDefinitions) {
@@ -81,7 +108,7 @@ export function normalizeSubagents(
       throw new FlexHarnessValidationError(`subagents[${index}] must be a plain object.`);
     }
     const unsupported = Object.keys(definition).find(
-      (key) => !['name', 'description', 'modelHint', 'system', 'maxSteps'].includes(key),
+      (key) => !['name', 'description', 'modelHint', 'system', 'maxSteps', 'allowedTools'].includes(key),
     );
     if (unsupported) {
       throw new FlexHarnessValidationError(`subagents[${index}] does not support "${unsupported}".`);
@@ -121,6 +148,9 @@ export function normalizeSubagents(
       ...(definition.modelHint === undefined ? {} : { modelHint: definition.modelHint }),
       ...(definition.system === undefined ? {} : { system: definition.system }),
       ...(definition.maxSteps === undefined ? {} : { maxSteps: definition.maxSteps }),
+      ...(definition.allowedTools === undefined ? {} : {
+        allowedTools: normalizeAllowedTools(definition.allowedTools, `subagents[${index}].allowedTools`),
+      }),
     }));
   }
   return Object.freeze(normalized);

package/ts/utils.json.ts

@@ -20,6 +20,7 @@ import type {
   TFlexAgentModelMessage,
   TJsonValue,
 } from './interfaces.js';
+import { isValidSessionConfigurationRef } from './utils.validation.js';
 
 const DEFAULT_MAX_DEPTH = 12;
 const DEFAULT_MAX_BYTES = 256 * 1024;
@@ -483,6 +484,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
       'sessionId',
       'sessionGenerationId',
       'sessionGenerationSequence',
+      'configurationRef',
       'title',
       'createdAt',
       'updatedAt',
@@ -502,6 +504,9 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   if (session.origin !== undefined) validateSessionOrigin(session.origin, `${path}.origin`);
   const sessionId = requireString(session.sessionId, `${path}.sessionId`);
   const generation = validateOptionalSessionGeneration(session, path);
+  if (session.configurationRef !== undefined && !isValidSessionConfigurationRef(session.configurationRef)) {
+    throw new FlexHarnessStoreFormatError(`${path}.configurationRef is invalid.`);
+  }
   requireOptionalString(session.title, `${path}.title`);
   requireString(session.createdAt, `${path}.createdAt`);
   requireString(session.updatedAt, `${path}.updatedAt`);
@@ -545,6 +550,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   return {
     sessionId,
     ...generation,
+    ...(session.configurationRef === undefined ? {} : { configurationRef: session.configurationRef as string }),
     ...(relationshipCount === 0
       ? {}
       : {
@@ -689,6 +695,7 @@ interface IValidatedSessionIdentity {
   sessionId: string;
   sessionGenerationId?: string;
   sessionGenerationSequence?: number;
+  configurationRef?: string;
   parentSessionId?: string;
   parentRunId?: string;
   parentToolCallId?: string;
@@ -889,6 +896,11 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
         `Snapshot child session "${session.sessionId}" has no live parent "${session.parentSessionId}".`,
       );
     }
+    if (session.configurationRef !== parent.configurationRef) {
+      throw new FlexHarnessStoreFormatError(
+        `Snapshot child session "${session.sessionId}" has a different configurationRef from its parent.`,
+      );
+    }
     const expectedDepth = (parent.depth ?? 0) + 1;
     if (session.depth !== expectedDepth) {
       throw new FlexHarnessStoreFormatError(

package/ts/utils.validation.ts

@@ -4,6 +4,7 @@ import {
   FLEX_PROJECT_MANAGEMENT_LIMITS,
   FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES,
   FLEX_SESSION_GENERATION_ID_MAX_BYTES,
+  FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES,
 } from './interfaces.js';
 import type {
   IFlexCompactSessionOptions,
@@ -23,6 +24,24 @@ const maxProjectedErrorNameBytes = 128;
 const maxProjectedErrorMessageBytes = 2048;
 const maxProjectedErrorCodeBytes = 128;
 const controlCharacterPattern = /[\u0000-\u001f\u007f]/u;
+const configurationControlCharacterPattern = /[\u0000-\u001f\u007f-\u009f]/u;
+const unpairedSurrogatePattern = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u;
+
+export function isValidSessionConfigurationRef(value: unknown): value is string {
+  return typeof value === 'string'
+    && Boolean(value.trim())
+    && Buffer.byteLength(value, 'utf8') <= FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES
+    && !configurationControlCharacterPattern.test(value)
+    && !unpairedSurrogatePattern.test(value);
+}
+
+export function validateSessionConfigurationRef(value: unknown): asserts value is string {
+  if (!isValidSessionConfigurationRef(value)) {
+    throw new FlexHarnessValidationError(
+      `configurationRef must be a non-empty well-formed string without control characters of at most ${FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES} UTF-8 bytes.`,
+    );
+  }
+}
 
 export function validateIdentifier(value: string, name: string): void {
   if (typeof value !== 'string' || value.length === 0) {