elastic · jonwalstedt · Sep 2, 2026 · Sep 4, 2026 · Sep 2, 2026 · Sep 4, 2026
@@ -0,0 +1,46 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+/**
+ * Matches a *whole-value* Liquid template expression such as `"${{ event.messages }}"` — the
+ * only template form whose resolved value keeps its native type (array, object, number)
+ * instead of being stringified.
+ *
+ * The shape is deliberately narrow, and each restriction mirrors the runtime in
+ * `WorkflowTemplatingEngine.renderValueRecursively`:
+ *
+ * - **`$` is required.** The engine returns the raw evaluated value only for strings matching
+ *   `startsWith('${{') && endsWith('}}')`. A bare `{{ expr }}` falls through to `renderString`
+ *   and always comes back as a string, so it can never satisfy an array-typed param.
+ * - **No leading or trailing whitespace.** That runtime check does not trim.
+ * - **No inner `}}`.** `evaluateExpression` slices from the first `{{` to the last `}}`, so a
+ *   concatenation like `"${{ a }}-${{ b }}"` would be parsed as the single invalid expression
+ *   `a }}-${{ b` and throw at execution time.
+ *
+ * The invariant this encodes is one-directional: everything matched here is type-preserved at
+ * runtime. The engine itself accepts a superset, and those extra forms stringify or throw —
+ * which is exactly why callers should validate against this rather than re-deriving the shape.
+ * `template_expressions_runtime.test.ts` in `workflows_execution_engine` pins the invariant.
+ */
+export const WHOLE_VALUE_TEMPLATE_EXPRESSION_REGEX = /^\$\{\{(?:(?!\}\})[\s\S])*\}\}$/;
+
+/**
+ * Upper bound on a whole-value Liquid template expression accepted where a connector param
+ * declares a non-string type. This is a sanity bound on a single YAML scalar, not a defence
+ * against large workflow payloads — the branch it widens (the param's own array/object schema)
+ * carries whatever bounds that connector declared, and this value does not change them.
+ */
+export const TEMPLATE_EXPRESSION_MAX_LENGTH = 500;
+
+/**
+ * Returns true when `value` is a whole-value Liquid template expression whose resolved value
+ * keeps its native type at runtime. See {@link WHOLE_VALUE_TEMPLATE_EXPRESSION_REGEX}.
+ */
+export const isWholeValueTemplateExpression = (value: string): boolean =>
+  WHOLE_VALUE_TEMPLATE_EXPRESSION_REGEX.test(value);
@@ -51,6 +51,7 @@ export * from './spec/deprecated_step_metadata';
 export * from './types/latest';
 export * from './types/utils';
 export * from './common/constants';
+export * from './common/template_expressions';
 export * from './common/validate_step_names';
 export * from './common/workflows_events';
 export type * from './common/event_trigger_replay';

@@ -65,6 +65,39 @@ describe('builtInStepDefinitions', () => {
   });
 });
 
+describe('supportedExecutionModes', () => {
+  // These steps depend on Task Manager — to suspend and resume the workflow, or to schedule
+  // work outside the current execution — so they can never complete inside a single HTTP
+  // request. `validateSyncWorkflow` refuses to run a workflow containing one of them in sync
+  // mode; if an annotation here is dropped, that guard silently stops firing and a synchronous
+  // request hangs instead of failing fast.
+  const ASYNC_ONLY_IDS = [
+    'wait',
+    'waitForInput',
+    'waitForApproval',
+    'workflow.execute',
+    'workflow.executeAsync',
+  ];
+
+  it.each(ASYNC_ONLY_IDS)('"%s" is declared async-only', (id) => {
+    expect(getBuiltInStepDefinition(id)?.supportedExecutionModes).toEqual(['async']);
+  });
+
+  it('lists every async-only built-in — a new Task Manager-dependent step must be added here', () => {
+    const declaredAsyncOnly = builtInStepDefinitions
+      .filter((def) => def.supportedExecutionModes?.includes('sync') === false)
+      .map((def) => def.id);
+    expect(declaredAsyncOnly.sort()).toEqual([...ASYNC_ONLY_IDS].sort());
+  });
+
+  it.each(['console', 'data.set', 'if', 'foreach'])(
+    '"%s" leaves the field unset, so it stays runnable in both modes',
+    (id) => {
+      expect(getBuiltInStepDefinition(id)?.supportedExecutionModes).toBeUndefined();
+    }
+  );
+});
+
 describe('getBuiltInStepDefinition', () => {
   it('returns the definition for a known id', () => {
     const def = getBuiltInStepDefinition('if');

@@ -234,6 +234,7 @@ export const builtInStepDefinitions: BaseStepDefinition[] = [
   },
   {
     id: 'wait',
+    supportedExecutionModes: ['async'],
     label: 'Wait',
     description: 'Pause execution for a specified duration',
     category: StepCategory.FlowControl,
@@ -267,6 +268,7 @@ export const builtInStepDefinitions: BaseStepDefinition[] = [
   },
   {
     id: 'workflow.execute',
+    supportedExecutionModes: ['async'],
     label: 'Execute Workflow',
     description: 'Execute another workflow and wait for it to complete',
     category: StepCategory.FlowControl,
@@ -286,6 +288,7 @@ export const builtInStepDefinitions: BaseStepDefinition[] = [
   },
   {
     id: 'waitForInput',
+    supportedExecutionModes: ['async'],
     label: 'Wait For Input',
     description: 'Pause execution until external input is provided (human-in-the-loop)',
     category: StepCategory.FlowControl,
@@ -328,6 +331,7 @@ export const builtInStepDefinitions: BaseStepDefinition[] = [
   },
   {
     id: 'waitForApproval',
+    supportedExecutionModes: ['async'],
     label: 'Wait For Approval',
     description: 'Pause execution until approval or rejection is received (human-in-the-loop)',
     category: StepCategory.FlowControl,
@@ -357,6 +361,7 @@ export const builtInStepDefinitions: BaseStepDefinition[] = [
   },
   {
     id: 'workflow.executeAsync',
+    supportedExecutionModes: ['async'],
     label: 'Execute Workflow (Async)',
     description: 'Start another workflow and continue without waiting for completion',
     category: StepCategory.FlowControl,

@@ -12,6 +12,7 @@ import {
   CONNECTOR_ID_MAX_LENGTH,
   type ConnectorContractUnion,
   generateYamlSchemaFromConnectors,
+  TEMPLATE_EXPRESSION_MAX_LENGTH,
 } from '../..';
 
 const BASE_WORKFLOW = {
@@ -218,4 +219,199 @@ describe('generateYamlSchemaFromConnectors', () => {
       expect(elapsed).toBeLessThan(500);
     });
   });
+
+  describe('withTemplateStringSupport (array field widening)', () => {
+    const arrayConnector: ConnectorContractUnion = {
+      summary: 'Notifier',
+      description: null,
+      type: 'notify',
+      paramsSchema: z.object({
+        recipients: z.array(z.string()),
+        subject: z.string(),
+      }),
+      outputSchema: z.unknown(),
+    };
+
+    const parse = (withValue: unknown) =>
+      generateYamlSchemaFromConnectors([arrayConnector]).safeParse({
+        ...BASE_WORKFLOW,
+        steps: [{ name: 'step', type: 'notify', with: withValue }],
+      });
+
+    it('accepts a ${{ expr }} template for an array param', () => {
+      expect(
+        parse({ recipients: '${{ workflow.inputs.recipients }}', subject: 'hi' }).success
+      ).toBe(true);
+    });
+
+    // Only `${{ … }}` survives as an array at runtime: WorkflowTemplatingEngine returns the raw
+    // evaluated value for that form only, and renders everything else to a string. Accepting any
+    // of the shapes below would let YAML be saved that hands the connector a string — or, for the
+    // multi-expression forms, throws "The provided expression is invalid" mid-execution, because
+    // evaluateExpression slices from the first `{{` to the last `}}`.
+    it.each([
+      ['a plain string', 'not-a-template'],
+      ['a bare {{ expr }} template (renders to a string, not an array)', '{{ recipients }}'],
+      ['text before the expression', 'prefix-${{ expr }}'],
+      ['text after the expression', '${{ expr }}-suffix'],
+      ['two concatenated expressions', '${{ a }}-${{ b }}'],
+      ['an expression with literal text between two others', '${{ a }} literal ${{ b }}'],
+      ['leading whitespace (the runtime check does not trim)', '  ${{ expr }}'],
+      ['trailing whitespace (the runtime check does not trim)', '${{ expr }}  '],
+    ])('rejects %s for an array param', (_label, recipients) => {
+      expect(parse({ recipients, subject: 'hi' }).success).toBe(false);
+    });
+
+    it('rejects a template string exceeding TEMPLATE_EXPRESSION_MAX_LENGTH', () => {
+      const long = `\${{ ${'x'.repeat(TEMPLATE_EXPRESSION_MAX_LENGTH)} }}`;
+      expect(parse({ recipients: long, subject: 'hi' }).success).toBe(false);
+    });
+
+    it('does not widen non-array fields — string params remain string-only', () => {
+      expect(parse({ recipients: ['a@b.com'], subject: '{{ not-widened }}' }).success).toBe(true);
+      // A real Liquid expression is still valid as a string value, but a plain array is not
+      expect(parse({ recipients: ['a@b.com'], subject: ['array', 'not', 'ok'] }).success).toBe(
+        false
+      );
+    });
+
+    it('widens optional array params and preserves optionality', () => {
+      const connector: ConnectorContractUnion = {
+        summary: 'Opt',
+        description: null,
+        type: 'opt.step',
+        paramsSchema: z.object({ tags: z.array(z.string()).optional() }),
+        outputSchema: z.unknown(),
+      };
+      const schema = generateYamlSchemaFromConnectors([connector]);
+      // template string accepted
+      expect(
+        schema.safeParse({
+          ...BASE_WORKFLOW,
+          steps: [{ name: 's', type: 'opt.step', with: { tags: '${{ workflow.inputs.tags }}' } }],
+        }).success
+      ).toBe(true);
+      // omitting the optional field is still valid
+      expect(
+        schema.safeParse({
+          ...BASE_WORKFLOW,
+          steps: [{ name: 's', type: 'opt.step', with: {} }],
+        }).success
+      ).toBe(true);
+    });
+
+    it('widens default-wrapped array params without making them required', () => {
+      const connector: ConnectorContractUnion = {
+        summary: 'Def',
+        description: null,
+        type: 'def.step',
+        // Mirrors a real shipped connector: InferenceRerankParamsSchema declares
+        // `input: z.array(z.string()).default([])` as a top-level param.
+        paramsSchema: z.object({ tags: z.array(z.string()).default([]), query: z.string() }),
+        outputSchema: z.unknown(),
+      };
+      const schema = generateYamlSchemaFromConnectors([connector]);
+      expect(
+        schema.safeParse({
+          ...BASE_WORKFLOW,
+          steps: [
+            {
+              name: 's',
+              type: 'def.step',
+              with: { tags: '${{ workflow.inputs.tags }}', query: 'q' },
+            },
+          ],
+        }).success
+      ).toBe(true);
+
+      // Widening must not strip `.default()`. If it did, every existing workflow that omits a
+      // defaulted array param would stop validating — including on update, since this schema
+      // gates persistence and not just editor feedback.
+      const omitted = schema.safeParse({
+        ...BASE_WORKFLOW,
+        steps: [{ name: 's', type: 'def.step', with: { query: 'q' } }],
+      });
+      expect(omitted.success).toBe(true);
+      expect(omitted.data).toMatchObject({ steps: [{ with: { tags: [] } }] });
+    });
+
+    it('widens array params wrapped in both .optional() and .default()', () => {
+      const connector: ConnectorContractUnion = {
+        summary: 'Both',
+        description: null,
+        type: 'both.step',
+        paramsSchema: z.object({ tags: z.array(z.string()).optional().default([]) }),
+        outputSchema: z.unknown(),
+      };
+      const schema = generateYamlSchemaFromConnectors([connector]);
+      // Stacked wrappers must still be unwrapped down to the array, otherwise the field is
+      // silently skipped and the template string is reported as a type error.
+      expect(
+        schema.safeParse({
+          ...BASE_WORKFLOW,
+          steps: [{ name: 's', type: 'both.step', with: { tags: '${{ workflow.inputs.tags }}' } }],
+        }).success
+      ).toBe(true);
+    });
+
+    it('preserves the object unknownKeys policy of the original paramsSchema', () => {
+      // A strict paramsSchema should still reject unknown keys after widening.
+      const connector: ConnectorContractUnion = {
+        summary: 'Strict',
+        description: null,
+        type: 'strict.step',
+        paramsSchema: z.strictObject({ ids: z.array(z.string()) }),
+        outputSchema: z.unknown(),
+      };
+      const schema = generateYamlSchemaFromConnectors([connector]);
+      expect(
+        schema.safeParse({
+          ...BASE_WORKFLOW,
+          steps: [
+            {
+              name: 's',
+              type: 'strict.step',
+              with: { ids: '${{ workflow.inputs.ids }}', unknown_key: 'bad' },
+            },
+          ],
+        }).success
+      ).toBe(false);
+    });
+
+    it('does not throw for a connector whose paramsSchema has object-level refinements', () => {
+      const connector: ConnectorContractUnion = {
+        summary: 'Refined',
+        description: null,
+        type: 'refined.step',
+        paramsSchema: z
+          .object({ ids: z.array(z.string()), name: z.string() })
+          .refine((v) => v.ids.length > 0, 'ids must not be empty'),
+        outputSchema: z.unknown(),
+      };
+      // Schema construction must not throw even though paramsSchema has a refinement.
+      expect(() => generateYamlSchemaFromConnectors([connector])).not.toThrow();
+
+      const schema = generateYamlSchemaFromConnectors([connector]);
+      // Template string still accepted for the array field.
+      expect(
+        schema.safeParse({
+          ...BASE_WORKFLOW,
+          steps: [
+            {
+              name: 's',
+              type: 'refined.step',
+              with: { ids: '${{ workflow.inputs.ids }}', name: 'x' },
+            },
+          ],
+        }).success
+      ).toBe(true);
+      // The object-level refinement is preserved: an empty ids array fails.
+      expect(
+        schema.safeParse({
+          ...BASE_WORKFLOW,
+          steps: [{ name: 's', type: 'refined.step', with: { ids: [], name: 'x' } }],
+        }).success
+      ).toBe(false);
+    });
+  });
 });