@scenario-labs/sdk 3.1.0 → 3.2.0

package/src/lib/workflow_converter.ts

@@ -55,9 +55,11 @@ export type WorkflowEditorNode =
       data: NodeCommonData & {
         from?: number | string;
         count?: number | string;
+        mode?: 'default' | 'randomize' | 'choose';
         isRandomize?: boolean;
         randomSeed?: string;
         isSeedLocked?: boolean;
+        message?: string;
         value?: string;
       };
     }
@@ -134,6 +136,11 @@ type ModelInputNodeData = NodeCommonData & {
 
 const RUNNABLE_TYPES = new Set(['model', 'llm', 'forEach', 'forEachEnd']);
 const MODEL_CUSTOM_INPUT_HANDLE_SUFFIX = '-source-custom';
+const USER_SELECTION_MIN_SELECT = 1;
+const USER_SELECTION_MAX_SELECT = 100;
+const DEFAULT_SLICE_ASSETS_CHOOSE_MESSAGE = 'Select the items to continue';
+
+type SliceAssetsMode = 'default' | 'randomize' | 'choose';
 
 export const ASPECT_RATIO_PRESETS = [
   '21:9',
@@ -176,6 +183,10 @@ export type WorkflowEditorFlowInput = {
   ref?: WorkflowEditorFlowInputRef | undefined;
   value?: string | number | string[] | boolean | undefined;
   items?: WorkflowEditorFlowInput[][] | undefined;
+  /** Inclusive minimum for number/array inputs. For user-selection, items the user must pick. */
+  min?: number | undefined;
+  /** Inclusive maximum for number/array inputs. For user-selection, items the user may pick. */
+  max?: number | undefined;
 };
 
 export type WorkflowEditorFlowItem = {
@@ -215,12 +226,17 @@ function nodeIdToFlowId(nodeId: string): string {
   return nodeId.replace(/\s/g, '');
 }
 
+/** CEL identifiers cannot contain hyphens (`loop2-end` parses as subtraction). */
+function toCelIdentifier(name: string): string {
+  return name.replaceAll('-', '_');
+}
+
 function escapeCELString(value: string): string {
   return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n');
 }
 
 function formatTextAsCELString(text: string): string {
-  return `'${text.replace(/'/g, "\\'").replace(/\n/g, '\\n')}'`;
+  return `'${escapeCELString(text)}'`;
 }
 
 function buildConcatArrayTransform(variables: ConcatVariable[]): string {
@@ -566,13 +582,33 @@ function hasHandleConnection(
 }
 
 function getOutputHandleVarName(targetNodeId: string, handleName: string): string {
-  return ['output', 'allOutputs'].includes(handleName) ? targetNodeId : `${targetNodeId}_${handleName}`;
+  return toCelIdentifier(
+    ['output', 'allOutputs'].includes(handleName) ? targetNodeId : `${targetNodeId}_${handleName}`,
+  );
 }
 
 function getIsSliceAssetsItemsSourceHandle(nodeId: string, sourceHandle: string | null | undefined): boolean {
   return sourceHandle === `${nodeId}-source-items` || sourceHandle === `${nodeId}-source-assets`;
 }
 
+/**
+ * Prompt Builder (transformText) binds upstream vars for CEL. Reuse the same
+ * list-producer rules as concat/slice (`groupItems`, `sliceAssets`, `allOutputs`,
+ * split-text, LLM "All Results", `isArray` handles): those nodes always emit CEL
+ * lists (via concat/slice/randomSample), so Prompt Builder must bind them as
+ * `string_array` for indexing. Scalar text (plain text nodes, forEach outputs)
+ * stays `string`.
+ */
+function getPromptBuilderInputType(
+  targetNode: WorkflowEditorNode,
+  outHandle: WorkflowEditorHandleOutput | undefined,
+  outHandleName: string,
+): 'string' | 'string_array' {
+  return getConcatListSourceDescriptor(targetNode, outHandle, outHandleName).inputType === 'string_array' ?
+      'string_array'
+    : 'string';
+}
+
 function getConcatListSourceDescriptor(
   targetNode: WorkflowEditorNode,
   outHandle: WorkflowEditorHandleOutput | undefined,
@@ -607,7 +643,7 @@ function getConcatListSourceDescriptor(
 
 /**
  * Builds the concat variables and flow inputs for a list-concatenating node
- * (groupItems, sliceAssets in randomize mode) from its incoming edges.
+ * (groupItems, sliceAssets in randomize/choose mode) from its incoming edges.
  * `getVarName` maps a target node id + output handle name to the variable name,
  * which differs between callers.
  */
@@ -1568,7 +1604,7 @@ export function convertWorkflowEditorToFlow(
       flow.push({
         id: flowId,
         type: 'transform',
-        logic: { transform: `'${escapeCELString(value)}'` },
+        logic: { transform: formatTextAsCELString(value) },
         inputs: flowInputs.length > 0 ? flowInputs : undefined,
       });
 
@@ -1601,7 +1637,7 @@ export function convertWorkflowEditorToFlow(
       flow.push({
         id: flowId,
         type: 'transform',
-        logic: { transform: `'${escapeCELString(value)}'` },
+        logic: { transform: formatTextAsCELString(value) },
         inputs: flowInputs.length > 0 ? flowInputs : undefined,
       });
 
@@ -1622,7 +1658,11 @@ export function convertWorkflowEditorToFlow(
         const outHandle = targetNode.data.outputHandles?.find((h) => h.id === edge.targetHandle);
         const outHandleName = outHandle?.name ?? 'output';
         const targetFlowId = nodeIdToFlowIdMap.get(targetNode.id) ?? targetNode.id;
-        flowInputs.push({ name: `${targetFlowId}_${outHandleName}`, type: 'string', ref });
+        flowInputs.push({
+          name: `${targetFlowId}_${outHandleName}`,
+          type: getPromptBuilderInputType(targetNode, outHandle, outHandleName),
+          ref,
+        });
       }
       flowInputs.push(...collectConditionalConnectionInputs(incomingEdges, node.id, ctx));
       flow.push({
@@ -1670,10 +1710,12 @@ export function convertWorkflowEditorToFlow(
       const { variables, flowInputs } = collectConcatVarsAndInputs(
         incomingEdges.filter((e) => e.sourceHandle !== conditionalHandleId),
         ctx,
-        (targetNodeId, handleName) => `${targetNodeId}_${handleName}`,
+        (targetNodeId, handleName) => toCelIdentifier(`${targetNodeId}_${handleName}`),
       );
 
-      const orderedValues = convertValueToList((node.data as { value?: string }).value ?? '');
+      const orderedValues = convertValueToList((node.data as { value?: string }).value ?? '').map(
+        toCelIdentifier,
+      );
       variables.sort((a, b) => orderedValues.indexOf(a.name) - orderedValues.indexOf(b.name));
       flowInputs.sort((a, b) => orderedValues.indexOf(a.name) - orderedValues.indexOf(b.name));
       flowInputs.push(...collectConditionalConnectionInputs(incomingEdges, node.id, ctx));
@@ -1685,16 +1727,19 @@ export function convertWorkflowEditorToFlow(
       });
 
       // ------------------------------------
-      // SliceAssets -> slice(list, from, from+count) or randomSample(list, count, seed)
+      // SliceAssets -> slice / randomSample transform, or user-selection in choose mode
       // ------------------------------------
     } else if (node.type === 'sliceAssets') {
       const sliceData = node.data as {
         from?: number | string;
         count?: number | string;
+        mode?: SliceAssetsMode;
         isRandomize?: boolean;
         randomSeed?: string;
         isSeedLocked?: boolean;
+        message?: string;
       };
+      const mode = getSliceAssetsMode(sliceData);
       const conditionalHandleId = getConditionalInputHandleId(node.id);
       const itemsEdges = incomingEdges.filter(
         (e) =>
@@ -1702,7 +1747,58 @@ export function convertWorkflowEditorToFlow(
           getIsSliceAssetsItemsSourceHandle(node.id, e.sourceHandle),
       );
 
-      if (sliceData.isRandomize) {
+      if (mode === 'choose') {
+        const connectionInputs = collectConditionalConnectionInputs(incomingEdges, node.id, ctx);
+
+        // No item sources → unsatisfiable selection; mirror default empty fallback.
+        if (itemsEdges.length === 0) {
+          flow.push({
+            id: flowId,
+            type: 'transform',
+            logic: { transform: '[]' },
+            inputs: connectionInputs.length > 0 ? connectionInputs : undefined,
+          });
+        } else {
+          const { variables, flowInputs } = collectConcatVarsAndInputs(
+            itemsEdges,
+            ctx,
+            getOutputHandleVarName,
+          );
+          const count = clampUserSelectionCount(parseInt(String(sliceData.count ?? ''), 10) || 1);
+          const message = sliceData.message?.trim() || DEFAULT_SLICE_ASSETS_CHOOSE_MESSAGE;
+          const arrayType = getUserSelectionArrayType(flowInputs);
+
+          // Single array-typed source can feed user-selection directly; scalars must be wrapped.
+          if (variables.length === 1 && variables[0]?.isArray && flowInputs[0]?.ref) {
+            flow.push({
+              id: flowId,
+              type: 'user-selection',
+              label: message,
+              inputs: [
+                { name: 'items', type: arrayType, ref: flowInputs[0].ref, min: count, max: count },
+                ...connectionInputs,
+              ],
+            });
+          } else {
+            const concatId = `${flowId}_items`;
+            flow.push({
+              id: concatId,
+              type: 'transform',
+              logic: { transform: buildConcatArrayTransform(variables) },
+              inputs: flowInputs.length > 0 ? flowInputs : undefined,
+            });
+            flow.push({
+              id: flowId,
+              type: 'user-selection',
+              label: message,
+              inputs: [
+                { name: 'items', type: arrayType, ref: { node: concatId }, min: count, max: count },
+                ...connectionInputs,
+              ],
+            });
+          }
+        }
+      } else if (mode === 'randomize') {
         const { variables, flowInputs } = collectConcatVarsAndInputs(itemsEdges, ctx, getOutputHandleVarName);
         flowInputs.push(...collectConditionalConnectionInputs(incomingEdges, node.id, ctx));
 
@@ -1737,7 +1833,7 @@ export function convertWorkflowEditorToFlow(
               from < 0 ?
                 `slice(${varName}, (${varName}).size() + ${from}, (${varName}).size() + ${from + count})`
               : `slice(${varName}, ${from}, ${from + count})`;
-            const flowInputs: WorkflowEditorFlowInput[] = [
+            const sliceFlowInputs: WorkflowEditorFlowInput[] = [
               { name: varName, type: inputType, ref },
               ...collectConditionalConnectionInputs(incomingEdges, node.id, ctx),
             ];
@@ -1745,7 +1841,7 @@ export function convertWorkflowEditorToFlow(
               id: flowId,
               type: 'transform',
               logic: { transform },
-              inputs: flowInputs.length > 0 ? flowInputs : undefined,
+              inputs: sliceFlowInputs.length > 0 ? sliceFlowInputs : undefined,
             });
           }
         }
@@ -1991,3 +2087,21 @@ function applyApprovalsToFlow({
     });
   }
 }
+
+// ---- SliceAssets / user-selection helpers ----
+
+function getSliceAssetsMode(data: { mode?: SliceAssetsMode; isRandomize?: boolean }): SliceAssetsMode {
+  if (data.mode === 'choose' || data.mode === 'randomize' || data.mode === 'default') {
+    return data.mode;
+  }
+  return data.isRandomize ? 'randomize' : 'default';
+}
+
+function clampUserSelectionCount(count: number): number {
+  return Math.min(USER_SELECTION_MAX_SELECT, Math.max(USER_SELECTION_MIN_SELECT, count));
+}
+
+function getUserSelectionArrayType(flowInputs: WorkflowEditorFlowInput[]): 'file_array' | 'string_array' {
+  const hasFile = flowInputs.some((input) => input.type === 'file' || input.type === 'file_array');
+  return hasFile || flowInputs.length === 0 ? 'file_array' : 'string_array';
+}

package/src/lib/workflow_validator.ts

@@ -8,9 +8,14 @@ const VALID_NODE_TYPES = new Set([
   'remove-background',
   'transform',
   'user-approval',
+  'user-selection',
   'workflow',
 ]);
 
+const USER_SELECTION_MIN_SELECT = 1;
+const USER_SELECTION_MAX_SELECT = 100;
+const USER_SELECTION_INPUT_TYPES = new Set(['file_array', 'string_array']);
+
 type RawRef = {
   node?: unknown;
   conditional?: unknown;
@@ -18,8 +23,11 @@ type RawRef = {
 
 type RawInput = {
   name?: unknown;
+  type?: unknown;
   ref?: RawRef;
   items?: unknown[][];
+  min?: unknown;
+  max?: unknown;
 };
 
 type RawNode = {
@@ -47,7 +55,9 @@ type RawNode = {
  *       - custom-model → modelId
  *       - workflow     → workflowId
  *       - logic        → logicType
- *       - for-each     → loopBodyNodeIds (non-empty) OR count (>0)
+ *       - for-each        → loopBodyNodeIds (non-empty) OR count (>0)
+ *       - user-selection  → exactly one file_array/string_array input (optional connection);
+ *                           input.min ≤ input.max
  *  5. Cross-references all point to node IDs that exist in the flow:
  *       - dependsOn entries
  *       - input ref.node (excluding "workflow" which is a reserved keyword)
@@ -101,6 +111,9 @@ export function validateWorkflowFlow(flow: unknown[]): void {
         );
       }
     }
+    if (type === 'user-selection') {
+      validateUserSelectionNode(label, node);
+    }
   }
 
   // Pass 2 — cross-reference checks (all node IDs are now collected)
@@ -165,3 +178,57 @@ function validateInputRefs(nodeId: string, input: RawInput, nodeIds: Set<string>
     }
   }
 }
+
+function validateUserSelectionNode(label: string, node: RawNode): void {
+  const inputs = Array.isArray(node.inputs) ? (node.inputs as RawInput[]) : [];
+  const selectionInputs = inputs.filter(
+    (input) => typeof input.type === 'string' && USER_SELECTION_INPUT_TYPES.has(input.type),
+  );
+  const otherInputs = inputs.filter(
+    (input) => !(typeof input.type === 'string' && USER_SELECTION_INPUT_TYPES.has(input.type)),
+  );
+
+  if (selectionInputs.length !== 1) {
+    throw new Error(
+      `Node ${label} (user-selection) must have exactly one input of type file_array or string_array`,
+    );
+  }
+  for (const input of otherInputs) {
+    if (input.type !== 'connection') {
+      throw new Error(
+        `Node ${label} (user-selection) only allows an optional connection input besides the selection array, got "${String(
+          input.type,
+        )}"`,
+      );
+    }
+  }
+
+  const input = selectionInputs[0]!;
+
+  const min = input.min === undefined ? USER_SELECTION_MIN_SELECT : input.min;
+  const max = input.max === undefined ? USER_SELECTION_MAX_SELECT : input.max;
+
+  if (
+    typeof min !== 'number' ||
+    !Number.isInteger(min) ||
+    min < USER_SELECTION_MIN_SELECT ||
+    min > USER_SELECTION_MAX_SELECT
+  ) {
+    throw new Error(
+      `Node ${label} (user-selection) input.min must be an integer between ${USER_SELECTION_MIN_SELECT} and ${USER_SELECTION_MAX_SELECT}`,
+    );
+  }
+  if (
+    typeof max !== 'number' ||
+    !Number.isInteger(max) ||
+    max < USER_SELECTION_MIN_SELECT ||
+    max > USER_SELECTION_MAX_SELECT
+  ) {
+    throw new Error(
+      `Node ${label} (user-selection) input.max must be an integer between ${USER_SELECTION_MIN_SELECT} and ${USER_SELECTION_MAX_SELECT}`,
+    );
+  }
+  if (min > max) {
+    throw new Error(`Node ${label} (user-selection) input.min (${min}) must be <= input.max (${max})`);
+  }
+}