@scenario-labs/sdk 3.3.0 → 3.4.0

package/lib/workflow_converter.mjs

@@ -1,9 +1,8 @@
 // Converts a workflow editor state (nodes + edges) to a flow array suitable for the Scenario API.
 // Ported from fawkes useConvertWorkflowToApp — pure function, no React dependencies.
+import { USER_SELECTION_MAX_CANDIDATES, USER_SELECTION_MIN_SELECT } from "./user_selection_limits.mjs";
 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';
 export const ASPECT_RATIO_PRESETS = [
     '21:9',
@@ -27,7 +26,12 @@ function toCelIdentifier(name) {
     return name.replaceAll('-', '_');
 }
 function escapeCELString(value) {
-    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n');
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
 }
 function formatTextAsCELString(text) {
     return `'${escapeCELString(text)}'`;
@@ -152,6 +156,7 @@ function getForEachFlowListInputDescriptor(args) {
         listProvider?.type === 'text' ||
         listProvider?.type === 'llm' ||
         listProvider?.type === 'transformText' ||
+        listProvider?.type === 'joinTexts' ||
         (outputHandle?.type === 'text' && !!outputHandle.isArray);
     return isText ?
         { name: `text${inputIndex}`, type: 'string_array' }
@@ -325,17 +330,41 @@ function getIsSliceAssetsItemsSourceHandle(nodeId, sourceHandle) {
     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`.
+ * True when `expression` treats `varName` as a CEL list via indexing, `size(x)`,
+ * or list macros (`.map` / `.filter` / …). This is a converter tolerance for
+ * flows that index a list producer (editor First/Last/Nth stores `x[0]` on
+ * `isArray` handles; agent/MCP/import flows may index without that flag). It is
+ * not Fawkes's preview rule: the webapp binds a list only when the handle has
+ * `isArray`. Intentionally narrow so Prompt Builder cannot be steered into
+ * list semantics through other CEL list idioms.
+ */
+function expressionUsesListVariable(expression, varName) {
+    const escaped = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return (new RegExp(`${escaped}\\s*\\[`).test(expression) ||
+        new RegExp(`\\bsize\\s*\\(\\s*${escaped}\\s*\\)`).test(expression) ||
+        new RegExp(`${escaped}\\s*\\.\\s*(map|filter|all|exists|exists_one)\\s*\\(`).test(expression));
+}
+/**
+ * Prompt Builder (transformText) binds upstream vars for CEL. List producers
+ * bind as `string_array` when the source handle is `isArray`, or when the
+ * expression indexes/uses the variable as a list (see
+ * `expressionUsesListVariable`). Otherwise bare refs stay `string` so the API
+ * collapses the list to its first item.
+ *
+ * Fawkes today omits `isArray` on Slice/Group Items on purpose: only `isArray`
+ * handles get an indexed insert (`x[0]`); every other list insert is bare `x`
+ * and must collapse to the first item. Adding `isArray` to those handles later
+ * requires migrating stored expressions (`x` → `x[0]`) in the same Fawkes
+ * release, or both preview and published flows break on `'…' + x`.
  */
-function getPromptBuilderInputType(targetNode, outHandle, outHandleName) {
-    return getConcatListSourceDescriptor(targetNode, outHandle, outHandleName).inputType === 'string_array' ?
-        'string_array'
-        : 'string';
+function getPromptBuilderInputType(targetNode, outHandle, outHandleName, expression, varName) {
+    if (getConcatListSourceDescriptor(targetNode, outHandle, outHandleName).inputType !== 'string_array') {
+        return 'string';
+    }
+    if (outHandle?.isArray || expressionUsesListVariable(expression, varName)) {
+        return 'string_array';
+    }
+    return 'string';
 }
 function getConcatListSourceDescriptor(targetNode, outHandle, outHandleName) {
     const isArray = (targetNode.type === 'asset' && !!targetNode.data.isMultiple) ||
@@ -552,12 +581,43 @@ function applyAspectRatioInputs(args) {
         });
     }
 }
-function getForEachBodyEditorNodeIds(forEachId, forEachEndId, edges, nodes) {
+function buildLoopGraph(nodes, edges) {
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    const isInternalForEachEdge = (e) => {
+        const target = nodeById.get(e.target);
+        return (nodeById.get(e.source)?.type === 'forEach' &&
+            target?.type === 'forEachEnd' &&
+            target.data.parentNodeId === e.source);
+    };
+    const push = (map, key, value) => {
+        const list = map.get(key);
+        if (list)
+            list.push(value);
+        else
+            map.set(key, [value]);
+    };
+    const graph = {
+        nodeById,
+        consumers: new Map(),
+        dataProviders: new Map(),
+        dataConsumers: new Map(),
+    };
+    for (const e of edges) {
+        push(graph.consumers, e.target, e.source);
+        if (isInternalForEachEdge(e) || nodeById.get(e.source)?.type === 'approval')
+            continue;
+        push(graph.dataProviders, e.source, e.target);
+        push(graph.dataConsumers, e.target, e.source);
+    }
+    return graph;
+}
+function getForEachBodyEditorNodeIds(forEachId, forEachEndId, edges, graph) {
     const bodyNodeIds = new Set();
     const queue = [];
     const escaped = forEachId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const itemHandle = new RegExp(`^${escaped}-output-\\d+$`);
     for (const edge of edges) {
-        if (edge.target === forEachId && edge.targetHandle?.match(new RegExp(`^${escaped}-output-\\d+$`))) {
+        if (edge.target === forEachId && edge.targetHandle && itemHandle.test(edge.targetHandle)) {
             queue.push(edge.source);
         }
     }
@@ -566,13 +626,12 @@ function getForEachBodyEditorNodeIds(forEachId, forEachEndId, edges, nodes) {
         if (nodeId === forEachEndId || bodyNodeIds.has(nodeId))
             continue;
         bodyNodeIds.add(nodeId);
-        for (const edge of edges) {
-            if (edge.target === nodeId && !bodyNodeIds.has(edge.source) && edge.source !== forEachEndId) {
-                queue.push(edge.source);
-            }
+        for (const consumer of graph.consumers.get(nodeId) ?? []) {
+            if (!bodyNodeIds.has(consumer) && consumer !== forEachEndId)
+                queue.push(consumer);
         }
     }
-    addRandomizeClosureToBody(bodyNodeIds, forEachEndId, edges, nodes);
+    addRandomizeClosureToBody(bodyNodeIds, forEachEndId, graph);
     return bodyNodeIds;
 }
 /**
@@ -586,28 +645,34 @@ function getForEachBodyEditorNodeIds(forEachId, forEachEndId, edges, nodes) {
  * for an UNLOCKED randomize node we mutate `bodyNodeIds` in place to also include
  * that node plus the deterministic chain down to the body, so the runtime clones
  * it per iteration and each iteration re-draws. We only pull it in when *every*
- * path out of it lands in the body — if it also feeds a node outside the loop,
- * cloning it would break that external consumer, so we leave it shared.
+ * path out of it lands in the body or in this loop's results — if it also feeds a
+ * node outside the loop, cloning it would break that external consumer, so we
+ * leave it shared.
+ *
+ * Loop nodes (any for-each or loop end outside the body) stop both walks: a
+ * loop's list is computed once, before the loop runs, so neither a loop nor what
+ * feeds its list may be cloned with another loop's body. A for-each in its own
+ * body would even expand again on every iteration. A node that reaches one stays
+ * shared.
  */
-function addRandomizeClosureToBody(bodyNodeIds, forEachEndId, edges, nodes) {
-    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+function addRandomizeClosureToBody(bodyNodeIds, forEachEndId, graph) {
+    const isLoopNode = (id) => {
+        const type = graph.nodeById.get(id)?.type;
+        return type === 'forEach' || type === 'forEachEnd';
+    };
     const isUnlockedRandomize = (id) => {
-        const data = nodeById.get(id)?.data;
-        return data?.isRandomize === true && data.isSeedLocked !== true;
+        const data = graph.nodeById.get(id)?.data;
+        return !!data && getSliceAssetsMode(data) === 'randomize' && data.isSeedLocked !== true;
     };
-    // edge convention: `{ source: consumer, target: provider }` — an input handle
-    // on `source` reads an output handle on `target`.
-    const providersOf = (id) => edges.filter((e) => e.source === id).map((e) => e.target);
-    const consumersOf = (id) => edges.filter((e) => e.target === id).map((e) => e.source);
-    // Every node strictly upstream of the body (its transitive input providers).
+    // The nodes that feed the body without going through a loop node.
     const upstream = new Set();
     const upstreamQueue = [...bodyNodeIds];
     while (upstreamQueue.length > 0) {
-        for (const provider of providersOf(upstreamQueue.pop())) {
-            if (provider !== forEachEndId && !bodyNodeIds.has(provider) && !upstream.has(provider)) {
-                upstream.add(provider);
-                upstreamQueue.push(provider);
-            }
+        for (const provider of graph.dataProviders.get(upstreamQueue.pop()) ?? []) {
+            if (bodyNodeIds.has(provider) || upstream.has(provider) || isLoopNode(provider))
+                continue;
+            upstream.add(provider);
+            upstreamQueue.push(provider);
         }
     }
     for (const randomId of upstream) {
@@ -619,18 +684,17 @@ function addRandomizeClosureToBody(bodyNodeIds, forEachEndId, edges, nodes) {
         let escapesLoop = false;
         while (chainQueue.length > 0) {
             const id = chainQueue.pop();
-            if (bodyNodeIds.has(id))
-                continue; // reached the loop body — a valid sink
-            chain.add(id);
-            const consumers = consumersOf(id);
-            if (consumers.length === 0) {
-                escapesLoop = true; // dead-end outside the loop → do not internalize
+            // The body and this loop's results are where a per-iteration draw belongs.
+            if (bodyNodeIds.has(id) || id === forEachEndId || chain.has(id))
+                continue;
+            const consumers = graph.dataConsumers.get(id) ?? [];
+            // Another loop, or a dead end outside the loop: the draw must stay shared.
+            if (isLoopNode(id) || consumers.length === 0) {
+                escapesLoop = true;
                 break;
             }
-            for (const consumer of consumers) {
-                if (!bodyNodeIds.has(consumer))
-                    chainQueue.push(consumer);
-            }
+            chain.add(id);
+            chainQueue.push(...consumers);
         }
         if (!escapesLoop)
             for (const id of chain)
@@ -842,13 +906,14 @@ export function convertWorkflowEditorToFlow(params) {
     const forEachBodyEditorNodeIds = new Map();
     const forEachLoopFlowIds = new Map();
     const forEachFlowItemRefs = new Map();
+    const loopGraph = buildLoopGraph(nodes, edges);
     for (const node of sortedNodes) {
         if (node.type !== 'forEach')
             continue;
         const endNode = nodes.find((n) => n.type === 'forEachEnd' && n.data.parentNodeId === node.id);
         if (!endNode)
             continue;
-        forEachBodyEditorNodeIds.set(node.id, getForEachBodyEditorNodeIds(node.id, endNode.id, edges, nodes));
+        forEachBodyEditorNodeIds.set(node.id, getForEachBodyEditorNodeIds(node.id, endNode.id, edges, loopGraph));
         forEachLoopFlowIds.set(node.id, []);
     }
     // Pre-populate video firstFrame/lastFrame transform IDs for input nodes
@@ -1200,9 +1265,10 @@ export function convertWorkflowEditorToFlow(params) {
                 const outHandle = targetNode.data.outputHandles?.find((h) => h.id === edge.targetHandle);
                 const outHandleName = outHandle?.name ?? 'output';
                 const targetFlowId = nodeIdToFlowIdMap.get(targetNode.id) ?? targetNode.id;
+                const varName = `${targetFlowId}_${outHandleName}`;
                 flowInputs.push({
-                    name: `${targetFlowId}_${outHandleName}`,
-                    type: getPromptBuilderInputType(targetNode, outHandle, outHandleName),
+                    name: varName,
+                    type: getPromptBuilderInputType(targetNode, outHandle, outHandleName, value, varName),
                     ref,
                 });
             }
@@ -1245,6 +1311,37 @@ export function convertWorkflowEditorToFlow(params) {
                 inputs: flowInputs.length > 0 ? flowInputs : undefined,
             });
             // ------------------------------------
+            // JoinTexts -> join string list into a single string
+            // ------------------------------------
+        }
+        else if (node.type === 'joinTexts') {
+            const flowInputs = [];
+            const conditionalHandleId = getConditionalInputHandleId(node.id);
+            let listSourceVarName;
+            for (const edge of incomingEdges) {
+                if (edge.sourceHandle === conditionalHandleId)
+                    continue;
+                const targetNode = nodes.find((n) => n.id === edge.target);
+                if (!targetNode)
+                    continue;
+                const ref = getSourceRef(edge, ctx);
+                if (!ref)
+                    continue;
+                const varName = toCelIdentifier(targetNode.id);
+                flowInputs.push({ name: varName, type: 'string_array', ref });
+                listSourceVarName = varName;
+            }
+            flowInputs.push(...collectConditionalConnectionInputs(incomingEdges, node.id, ctx));
+            const delim = node.data.joinDelimiter ?? ', ';
+            flow.push({
+                id: flowId,
+                type: 'transform',
+                logic: {
+                    transform: `${listSourceVarName ?? '[]'}.join(${formatTextAsCELString(delim)})`,
+                },
+                inputs: flowInputs.length > 0 ? flowInputs : undefined,
+            });
+            // ------------------------------------
             // GroupItems -> array concatenation
             // ------------------------------------
         }
@@ -1285,7 +1382,9 @@ export function convertWorkflowEditorToFlow(params) {
                 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 message = typeof sliceData.message === 'string' ?
+                        sliceData.message.trim() || DEFAULT_SLICE_ASSETS_CHOOSE_MESSAGE
+                        : 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) {
@@ -1417,6 +1516,9 @@ export function convertWorkflowEditorToFlow(params) {
                         fieldsUsed.add(condition.field);
                 }
             }
+            // CEL conditions need hyphen→underscore identifiers, but the shared input-name
+            // map must keep the real workflow input keys (`text-1`, not `text_1`).
+            const celFieldNameMap = new Map();
             const edgesIntoIfElse = edges.filter((e) => e.target === node.id);
             for (const fieldKey of fieldsUsed) {
                 const resolved = resolveIfElseConditionField(fieldKey, nodes);
@@ -1429,7 +1531,7 @@ export function convertWorkflowEditorToFlow(params) {
                         ?.data.outputHandles?.find((h) => h.id === resolved.targetHandleId)?.name ?? 'output'
                     : 'output';
                 const celVarName = getOutputHandleVarName(fieldNodeId, outputHandleName);
-                nodeIdToInputNameMap.set(fieldKey, celVarName);
+                celFieldNameMap.set(fieldKey, celVarName);
                 const edgeToIfElse = edgesIntoIfElse
                     .filter((e) => e.source === fieldNodeId)
                     .find((e) => {
@@ -1463,7 +1565,7 @@ export function convertWorkflowEditorToFlow(params) {
             }
             const cases = [];
             for (let i = 0; i < conditionBlocks.length; i++) {
-                const condition = conditionBlockToCEL(conditionBlocks[i], nodeIdToInputNameMap);
+                const condition = conditionBlockToCEL(conditionBlocks[i], celFieldNameMap);
                 if (condition)
                     cases.push({ condition, value: String(i + 2) });
             }
@@ -1570,7 +1672,7 @@ function getSliceAssetsMode(data) {
     return data.isRandomize ? 'randomize' : 'default';
 }
 function clampUserSelectionCount(count) {
-    return Math.min(USER_SELECTION_MAX_SELECT, Math.max(USER_SELECTION_MIN_SELECT, count));
+    return Math.min(USER_SELECTION_MAX_CANDIDATES, Math.max(USER_SELECTION_MIN_SELECT, count));
 }
 function getUserSelectionArrayType(flowInputs) {
     const hasFile = flowInputs.some((input) => input.type === 'file' || input.type === 'file_array');