feat(workflow-executor): PRD-553 apply build-time filters on 1–n Load Related Record

packages/workflow-executor/src/adapters/agent-client-agent-port.ts

@@ -11,7 +11,7 @@ import type {
 import type SchemaCache from '../schema-cache';
 import type { StepUser } from '../types/execution-context';
 import type { RecordData } from '../types/validated/collection';
-import type { ActionEndpointsByCollection } from '@forestadmin/agent-client';
+import type { ActionEndpointsByCollection, SelectOptions } from '@forestadmin/agent-client';
 
 import { HttpRequester, createRemoteAgentClient } from '@forestadmin/agent-client';
 import jsonwebtoken from 'jsonwebtoken';
@@ -109,7 +109,7 @@ export default class AgentClientAgentPort implements AgentPort {
   }
 
   async getRelatedData(
-    { collection, id, relation, relatedSchema, limit, fields }: GetRelatedDataQuery,
+    { collection, id, relation, relatedSchema, limit, fields, filters }: GetRelatedDataQuery,
     user: StepUser,
   ): Promise<RecordData[]> {
     return this.callAgent('getRelatedData', async () => {
@@ -120,6 +120,7 @@ export default class AgentClientAgentPort implements AgentPort {
         .list<Record<string, unknown>>({
           ...(limit !== null && { pagination: { size: limit, number: 1 } }),
           ...(fields?.length && { fields }),
+          ...(filters !== undefined && { filters: filters as SelectOptions['filters'] }),
         });
 
       return rows.map(row => {

packages/workflow-executor/src/executors/load-related-record-step-executor.ts

@@ -562,6 +562,7 @@ export default class LoadRelatedRecordStepExecutor extends RecordStepExecutor<Lo
       relation: target.name,
       relatedSchema,
       limit,
+      filters: this.context.stepDefinition.preRecordedArgs?.filters,
     });
   }
 

packages/workflow-executor/src/ports/agent-port.ts

@@ -17,6 +17,7 @@ export type GetRelatedDataQuery = {
   // record ID and restore original field names without consulting any cache.
   relatedSchema: CollectionSchema;
   fields?: string[];
+  filters?: unknown;
 } & Limit;
 
 // xToOne relations (BelongsTo / HasOne) — the agent does not serve

packages/workflow-executor/src/types/validated/step-definition.ts

@@ -106,6 +106,8 @@ export const LoadRelatedRecordStepDefinitionSchema = z.object({
       selectedRecordStepId: z.string().optional(),
       /** "From collection" — the relation to follow (technical name) */
       relationName: z.string().optional(),
+      /** 1–n relation filter (conditionTree), forwarded verbatim; loosely typed as it's trusted config the agent validates. */
+      filters: z.unknown().optional(),
     })
     .optional(),
 });

packages/workflow-executor/test/executors/load-related-record-step-executor.test.ts

@@ -576,6 +576,124 @@
       );
     });
 
+    it('forwards a build-time filter (PRD-553) to getRelatedData on the 1–n list fetch', async () => {
+      const hasManySchema = makeCollectionSchema({
+        fields: [
+          {
+            fieldName: 'address',
+            displayName: 'Address',
+            isRelationship: true,
+            relationType: 'HasMany',
+            relatedCollectionName: 'addresses',
+          },
+        ],
+      });
+      const relatedData: RecordData[] = [
+        { collectionName: 'addresses', recordId: [1], values: { city: 'Paris' } },
+        { collectionName: 'addresses', recordId: [2], values: { city: 'Lyon' } },
+      ];
+      const agentPort = makeMockAgentPort(relatedData);
+      const addressSchema = makeCollectionSchema({
+        collectionName: 'addresses',
+        collectionDisplayName: 'Addresses',
+        fields: [{ fieldName: 'city', displayName: 'City', isRelationship: false }],
+      });
+      const invoke = jest
+        .fn()
+        .mockResolvedValueOnce({
+          tool_calls: [{ name: 'select-fields', args: { fieldNames: ['City'] }, id: 'c2' }],
+        })
+        .mockResolvedValueOnce({
+          tool_calls: [
+            {
+              name: 'select-record-by-content',
+              args: { recordIndex: 0, reasoning: 'r' },
+              id: 'c3',
+            },
+          ],
+        });
+      const model = {
+        bindTools: jest.fn().mockReturnValue({ invoke }),
+      } as unknown as ExecutionContext['model'];
+
+      const filters = { field: 'city', operator: 'equal', value: 'Lyon' };
+      const context = makeContext({
+        model,
+        agentPort,
+        workflowPort: makeMockWorkflowPort({ customers: hasManySchema, addresses: addressSchema }),
+        stepDefinition: makeStep({
+          executionType: StepExecutionMode.FullyAutomated,
+          preRecordedArgs: { relationName: 'address', filters },
+        }),
+      });
+
+      await new LoadRelatedRecordStepExecutor(context).execute();
+
+      expect(agentPort.getRelatedData).toHaveBeenCalledWith(
+        expect.objectContaining({ collection: 'customers', relation: 'address', filters }),
+        expect.anything(),
+      );
+    });
+
+    it('also forwards the filter on the AutomatedWithConfirmation path (the user-facing list)', async () => {
+      const hasManySchema = makeCollectionSchema({
+        fields: [
+          {
+            fieldName: 'address',
+            displayName: 'Address',
+            isRelationship: true,
+            relationType: 'HasMany',
+            relatedCollectionName: 'addresses',
+          },
+        ],
+      });
+      const relatedData: RecordData[] = [
+        { collectionName: 'addresses', recordId: [1], values: { city: 'Paris' } },
+        { collectionName: 'addresses', recordId: [2], values: { city: 'Lyon' } },
+      ];
+      const agentPort = makeMockAgentPort(relatedData);
+      const addressSchema = makeCollectionSchema({
+        collectionName: 'addresses',
+        collectionDisplayName: 'Addresses',
+        fields: [{ fieldName: 'city', displayName: 'City', isRelationship: false }],
+      });
+      const invoke = jest
+        .fn()
+        .mockResolvedValueOnce({
+          tool_calls: [{ name: 'select-fields', args: { fieldNames: ['City'] }, id: 'c2' }],
+        })
+        .mockResolvedValueOnce({
+          tool_calls: [
+            {
+              name: 'select-record-by-content',
+              args: { recordIndex: 0, reasoning: 'r' },
+              id: 'c3',
+            },
+          ],
+        });
+      const model = {
+        bindTools: jest.fn().mockReturnValue({ invoke }),
+      } as unknown as ExecutionContext['model'];
+
+      const filters = { field: 'city', operator: 'equal', value: 'Lyon' };
+      const context = makeContext({
+        model,
+        agentPort,
+        workflowPort: makeMockWorkflowPort({ customers: hasManySchema, addresses: addressSchema }),
+        stepDefinition: makeStep({
+          executionType: StepExecutionMode.AutomatedWithConfirmation,
+          preRecordedArgs: { relationName: 'address', filters },
+        }),
+      });
+
+      await new LoadRelatedRecordStepExecutor(context).execute();
+
+      expect(agentPort.getRelatedData).toHaveBeenCalledWith(
+        expect.objectContaining({ collection: 'customers', relation: 'address', filters }),
+        expect.anything(),
+      );
+    });
+
     it('skips field-selection AI call when related collection has no non-relation fields', async () => {
       const hasManySchema = makeCollectionSchema({
         fields: [
@@ -2158,7 +2276,7 @@
 
       await new LoadRelatedRecordStepExecutor(context).execute();
 
       const firstRow = JSON.parse(selectRecordPrompt(invoke).match(/\[0\] (\{[^\n]*\})/)![1]);
       expect(Object.keys(firstRow)).toHaveLength(6);
     });