@modelprofile.com/flexharness 5.2.0 → 5.3.1

package/ts/interfaces.ts

@@ -441,6 +441,7 @@ export interface IFlexSessionTombstone {
   rootSessionId?: string;
   depth?: number;
   parentSessionId?: string;
+  subagent?: IFlexSubagentProvenance;
 }
 
 export interface IFlexScopeSnapshot {
@@ -582,6 +583,16 @@ export interface IFlexSessionGeneration {
   sessionGenerationSequence: number;
 }
 
+export interface IFlexSubagentProvenance {
+  readonly parentSessionId: string;
+  readonly parentSessionGenerationId: string;
+  readonly parentSessionGenerationSequence: number;
+  readonly originParentRunId: string;
+  readonly originParentToolCallId: string;
+  readonly agent: string;
+  readonly depth: number;
+}
+
 export interface IFlexSessionGenerationCohortEntry extends IFlexSessionGeneration {
   sessionId: string;
 }
@@ -649,11 +660,15 @@ export interface IFlexProjectManagementWriteContext {
   toolCallId?: string;
 }
 
+export interface IFlexProjectManagementSessionContext extends IFlexSessionGeneration {
+  readonly subagent?: Readonly<IFlexSubagentProvenance>;
+}
+
 export interface IFlexProjectManagementStore {
   load(
     storageKey: string,
     sessionId: string,
-    sessionGeneration?: Readonly<IFlexSessionGeneration>,
+    sessionContext?: Readonly<IFlexProjectManagementSessionContext>,
   ): Promise<TFlexProjectManagementRecord | undefined>;
   save(
     storageKey: string,
@@ -667,6 +682,7 @@ export interface IFlexProjectManagementStore {
     sessionId: string,
     tombstone: IFlexProjectManagementTombstone,
     expectedRevision: number,
+    sessionContext?: Readonly<IFlexProjectManagementSessionContext>,
   ): Promise<void>;
   purgeNamespace(storageKey: string): Promise<void>;
 }
@@ -944,6 +960,7 @@ export interface IFlexRedoSessionResult {
 export type TFlexExternalErrorSource =
   | 'modelResolver'
   | 'toolProvider'
+  | 'delegatedRunAdmissionProvider'
   | 'toolExecution'
   | 'toolCallback'
   | 'toolCleanup'
@@ -964,6 +981,39 @@ export type TFlexExternalErrorProjector = (
   context: IFlexExternalErrorContext,
 ) => IFlexErrorInfo;
 
+export interface IFlexDelegatedRunAdmissionContext<TScope> extends IFlexSessionGeneration {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly sessionGenerationId: string;
+  readonly sessionGenerationSequence: number;
+  readonly queueId: string;
+  readonly runId: string;
+  readonly parentSessionId: string;
+  readonly parentSessionGenerationId: string;
+  readonly parentSessionGenerationSequence: number;
+  readonly parentQueueId: string;
+  readonly parentRunId: string;
+  readonly parentToolCallId: string;
+  readonly originParentRunId: string;
+  readonly originParentToolCallId: string;
+  readonly agent: string;
+  readonly depth: number;
+  readonly signal: AbortSignal;
+}
+
+export interface IFlexDelegatedRunAdmissionLease {
+  /** Must be idempotent and safe to retry after a rejected close attempt. */
+  close(): Promise<void> | void;
+}
+
+export interface IFlexDelegatedRunAdmissionProvider<TScope> {
+  acquireDelegatedRunAdmission(
+    context: IFlexDelegatedRunAdmissionContext<TScope>,
+  ): Promise<IFlexDelegatedRunAdmissionLease> | IFlexDelegatedRunAdmissionLease;
+}
+
 export interface IFlexExecutionContextProviderContext<TScope> {
   scopeId: string;
   scope: TScope;
@@ -1035,6 +1085,7 @@ export interface IFlexHarnessOptions<TScope> {
   toolProvider?: IFlexToolProvider<TScope>;
   resourceToolProviderResolver?: IFlexResourceToolProviderResolver<TScope>;
   executionContextProvider?: IFlexExecutionContextProvider<TScope>;
+  delegatedRunAdmissionProvider?: IFlexDelegatedRunAdmissionProvider<TScope>;
   stores?: IFlexHarnessStores;
   agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
   toolOutputLimits?: IFlexJsonLimits;

package/ts/utils.json.ts

@@ -15,6 +15,7 @@ import type {
   IFlexProjectionSnapshotV2,
   IFlexProjectionSnapshotV3,
   IFlexScopeSnapshot,
+  IFlexSubagentProvenance,
   TFlexAgentModelMessage,
   TJsonValue,
 } from './interfaces.js';
@@ -546,6 +547,68 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   };
 }
 
+function validateSubagentProvenance(
+  value: unknown,
+  path: string,
+): IFlexSubagentProvenance {
+  const provenance = requireRecord(value, path);
+  requireOnlyKeys(provenance, [
+    'parentSessionId',
+    'parentSessionGenerationId',
+    'parentSessionGenerationSequence',
+    'originParentRunId',
+    'originParentToolCallId',
+    'agent',
+    'depth',
+  ], path);
+  const parentSessionId = requireString(
+    provenance.parentSessionId,
+    `${path}.parentSessionId`,
+  );
+  const parentSessionGenerationId = requireString(
+    provenance.parentSessionGenerationId,
+    `${path}.parentSessionGenerationId`,
+  );
+  if (
+    Buffer.byteLength(parentSessionGenerationId, 'utf8')
+      > FLEX_SESSION_GENERATION_ID_MAX_BYTES
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.parentSessionGenerationId exceeds ${FLEX_SESSION_GENERATION_ID_MAX_BYTES} UTF-8 bytes.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(provenance.parentSessionGenerationSequence)
+    || Number(provenance.parentSessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.parentSessionGenerationSequence must be a positive integer.`,
+    );
+  }
+  const originParentRunId = requireString(
+    provenance.originParentRunId,
+    `${path}.originParentRunId`,
+  );
+  const originParentToolCallId = requireString(
+    provenance.originParentToolCallId,
+    `${path}.originParentToolCallId`,
+  );
+  const agent = requireString(provenance.agent, `${path}.agent`);
+  requireNonNegativeInteger(provenance.depth, `${path}.depth`);
+  if (provenance.depth === 0) {
+    throw new FlexHarnessStoreFormatError(`${path}.depth must be positive.`);
+  }
+  return {
+    parentSessionId,
+    parentSessionGenerationId,
+    parentSessionGenerationSequence: provenance.parentSessionGenerationSequence as number,
+    originParentRunId,
+    originParentToolCallId,
+    agent,
+    depth: provenance.depth as number,
+  };
+}
+
 function validateModel(value: unknown, path: string): void {
   const model = requireRecord(value, path);
   requireOnlyKeys(model, ['provider', 'model', 'displayName', 'variant'], path);
@@ -811,9 +874,12 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
   const tombstoneIds = new Set<string>();
   const tombstones = new Map<string, {
     sessionId: string;
+    sessionGenerationId?: string;
+    sessionGenerationSequence?: number;
     rootSessionId?: string;
     depth?: number;
     parentSessionId?: string;
+    subagent?: IFlexSubagentProvenance;
   }>();
   for (let index = 0; index < snapshot.tombstones.length; index++) {
     const path = `$snapshot.tombstones[${index}]`;
@@ -828,11 +894,12 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
         'rootSessionId',
         'depth',
         'parentSessionId',
+        'subagent',
       ],
       path,
     );
     const sessionId = requireString(tombstone.sessionId, `${path}.sessionId`);
-    validateOptionalSessionGeneration(tombstone, path);
+    const generation = validateOptionalSessionGeneration(tombstone, path);
     requireString(tombstone.deletedAt, `${path}.deletedAt`);
     const parentSessionId = tombstone.parentSessionId === undefined
       ? undefined
@@ -840,6 +907,19 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
     if (parentSessionId === sessionId) {
       throw new FlexHarnessStoreFormatError(`${path} cannot be its own parent.`);
     }
+    const subagent = tombstone.subagent === undefined
+      ? undefined
+      : validateSubagentProvenance(tombstone.subagent, `${path}.subagent`);
+    if (subagent && generation.sessionGenerationId === undefined) {
+      throw new FlexHarnessStoreFormatError(
+        `${path}.subagent requires exact session generation fields.`,
+      );
+    }
+    if (subagent && subagent.parentSessionId !== parentSessionId) {
+      throw new FlexHarnessStoreFormatError(
+        `${path}.subagent does not match its parentSessionId.`,
+      );
+    }
     const hasRoot = tombstone.rootSessionId !== undefined;
     const hasDepth = tombstone.depth !== undefined;
     if (hasRoot !== hasDepth) {
@@ -864,11 +944,26 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
       );
     }
     tombstoneIds.add(sessionId);
+    if (subagent) {
+      const origin = JSON.stringify([
+        subagent.parentSessionId,
+        subagent.originParentRunId,
+        subagent.originParentToolCallId,
+      ]);
+      if (origins.has(origin)) {
+        throw new FlexHarnessStoreFormatError(
+          'Snapshot contains duplicate subagent invocation origins.',
+        );
+      }
+      origins.add(origin);
+    }
     tombstones.set(sessionId, {
       sessionId,
+      ...generation,
       ...(hasRoot ? { rootSessionId: tombstone.rootSessionId as string } : {}),
       ...(hasDepth ? { depth: tombstone.depth as number } : {}),
       ...(parentSessionId === undefined ? {} : { parentSessionId }),
+      ...(subagent === undefined ? {} : { subagent }),
     });
   }
   for (const [index, tombstone] of snapshot.tombstones.entries()) {
@@ -894,6 +989,26 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
         `Snapshot tombstone "${tombstone.sessionId}" has no parent "${tombstone.parentSessionId}".`,
       );
     }
+    if (tombstone.subagent) {
+      const parent = parentSession ?? parentTombstone!;
+      if (
+        parent.sessionGenerationId !== tombstone.subagent.parentSessionGenerationId
+        || parent.sessionGenerationSequence
+          !== tombstone.subagent.parentSessionGenerationSequence
+      ) {
+        throw new FlexHarnessStoreFormatError(
+          `Snapshot tombstone "${tombstone.sessionId}" has inconsistent parent generation provenance.`,
+        );
+      }
+      const parentDepth = parent.parentSessionId === undefined
+        ? 0
+        : parentSession?.depth ?? parentTombstone?.subagent?.depth;
+      if (parentDepth === undefined || tombstone.subagent.depth !== parentDepth + 1) {
+        throw new FlexHarnessStoreFormatError(
+          `Snapshot tombstone "${tombstone.sessionId}" has inconsistent session depth provenance.`,
+        );
+      }
+    }
     if (tombstone.depth !== undefined && tombstone.depth > 0) {
       if (
         !parentTombstone