@scenario-labs/sdk 3.1.0 → 3.3.0

package/src/lib/query.ts

@@ -0,0 +1,42 @@
+import type { FinalRequestOptions } from '../internal/request-options';
+
+/**
+ * Keep unset query values from erasing the client's `defaultQuery`.
+ *
+ * Generated methods build their typed query with every key, set or not:
+ * `{ dryRun, projectId, ...options?.query }` yields `projectId: undefined` when
+ * the caller did not pass one. `buildURL` then spreads that object over the
+ * client's `defaultQuery`, so the unset key erases the client-level `projectId`
+ * and the request goes out unscoped — the API then falls back to the team's
+ * default project.
+ *
+ * So, on a new object (the query may be the caller's own params object):
+ * - `undefined` is dropped everywhere (the query serializer skips it anyway);
+ * - `null` and `''` are dropped only for keys `defaultQuery` provides, so the
+ *   default applies. Elsewhere they keep their usual serialization (`key=`).
+ *
+ * Called from the enhanced client's `prepareOptions`, i.e. on every request
+ * (retries included — it is idempotent).
+ */
+export function normalizeQuery(
+  options: FinalRequestOptions,
+  defaultQuery: Record<string, unknown> | undefined,
+): void {
+  const query = options.query;
+  // Only plain objects: rebuilding a URLSearchParams, a Map or a class instance
+  // from its own enumerable entries would silently empty it.
+  if (typeof query !== 'object' || query === null) return;
+  const proto = Object.getPrototypeOf(query);
+  if (proto !== Object.prototype && proto !== null) return;
+  options.query = Object.fromEntries(
+    Object.entries(query).filter(
+      ([key, value]) =>
+        value !== undefined &&
+        !(
+          defaultQuery &&
+          Object.prototype.hasOwnProperty.call(defaultQuery, key) &&
+          (value === null || value === '')
+        ),
+    ),
+  );
+}

package/src/lib/scenario.ts

@@ -1,8 +1,10 @@
 import { Scenario as BaseScenario, type ClientOptions as BaseClientOptions } from '../client';
+import type { FinalRequestOptions } from '../internal/request-options';
 import { EnhancedAssets } from './asset';
 import { EnhancedGenerate } from './generate';
 import { EnhancedJobs } from './job';
 import { EnhancedModels } from './models';
+import { normalizeQuery } from './query';
 import { EnhancedUploads } from './upload';
 import { EnhancedWorkflows } from './workflow';
 
@@ -82,6 +84,12 @@ export class Scenario extends BaseScenario {
     } as BaseClientOptions);
     this.projectId = projectId ?? null;
   }
+
+  /** Keep unset query values from erasing the client's `defaultQuery` (see `./query`). */
+  protected override async prepareOptions(options: FinalRequestOptions): Promise<void> {
+    await super.prepareOptions(options);
+    normalizeQuery(options, this.defaultQuery());
+  }
 }
 
 function stripKey<T extends object>(obj: T | undefined, key: string): Partial<T> | undefined {

package/src/lib/scope.ts

@@ -26,15 +26,50 @@ export function extractScope(options?: RequestOptions): Scope | undefined {
   return { projectId };
 }
 
+/** Read the typed `projectId` param of a call (`params`, `query` or `body`). Returns `undefined` if absent. */
+export function paramsProjectId(params: unknown): string | undefined {
+  if (!params || typeof params !== 'object') return undefined;
+  const projectId = (params as Record<string, unknown>)['projectId'];
+  return typeof projectId === 'string' && projectId ? projectId : undefined;
+}
+
+/**
+ * The project a request was actually sent to, read from its final options —
+ * the ones `APIResponseProps.options` carries, after the generated method
+ * merged typed params with `options.query` and `prepareOptions` normalized
+ * the query. Its `projectId` if it holds one, else the client default that
+ * `buildURL` merges in; `undefined` with neither (e.g. API-key auth with
+ * implicit scope).
+ *
+ * Reading the request instead of predicting it from params and options keeps
+ * this right whatever the generated merge does. Capture it on enhanced
+ * entities so that follow-up helper calls (`.wait()`, `entity.run()`, ...)
+ * stay in the project the originating request went to.
+ */
+export function sentScope(
+  finalOptions: RequestOptions,
+  clientDefault: string | null | undefined,
+): Scope | undefined {
+  const projectId = extractScope(finalOptions)?.projectId ?? clientDefault;
+  return projectId ? { projectId } : undefined;
+}
+
+/**
+ * Whether a call names its project itself, with a non-empty `projectId` in
+ * its typed params or in `options.query`. Only then must a scope captured
+ * earlier not be replayed over it; an unset value (`undefined`, `null`, `''`,
+ * e.g. from an optional spread) leaves the captured scope in charge.
+ */
+export function hasExplicitProjectId(options: RequestOptions | undefined, params: unknown): boolean {
+  return paramsProjectId(params) !== undefined || extractScope(options) !== undefined;
+}
+
 /**
- * Resolve the effective scope for an outgoing call:
- *   1. If the per-call options carry a `projectId` query — use that (the explicit override wins).
- *   2. Otherwise, fall back to the client's default `projectId`.
- *   3. If neither is set (e.g. API-key auth with implicit scope), return `undefined`.
+ * Two-tier resolution (`options.query.projectId`, else a fallback) that
+ * ignores typed params.
  *
- * Returns the snapshot we want to *capture on an enhanced entity* so that
- * follow-up helper calls (`.wait()`, `entity.run()`, ...) reuse the same
- * scope and stay in sync with the call that produced them.
+ * @deprecated Predicts the scope instead of reading it from the request.
+ * Use {@link sentScope} on the final request options.
  */
 export function effectiveScope(
   options: RequestOptions | undefined,

package/src/lib/upload.ts

@@ -12,7 +12,7 @@ import {
 } from '../resources/uploads';
 import type { AssetRetrieveResponse } from '../resources/assets/assets';
 import type { ModelRetrieveResponse } from '../resources/models/models';
-import { type Scope, clientProjectId, effectiveScope, withScope } from './scope';
+import { type Scope, clientProjectId, sentScope, withScope } from './scope';
 
 type UploadKind = NonNullable<UploadCreateParams['kind']>;
 
@@ -149,12 +149,14 @@ export type WithUpload<T extends { upload: unknown }> = T & { upload: UploadMeth
 export function enhanceUpload<T extends { upload: { id: string; status: string } }>(
   client: Scenario,
   promise: APIPromise<T>,
-  options?: RequestOptions,
 ): APIPromise<WithUpload<T>> {
-  const scope = effectiveScope(options, clientProjectId(client));
-  return promise._thenUnwrap((data) => ({
+  return promise._thenUnwrap((data, props) => ({
     ...data,
-    upload: Upload.from(client, data.upload as UploadRetrieveResponse['upload'], scope),
+    upload: Upload.from(
+      client,
+      data.upload as UploadRetrieveResponse['upload'],
+      sentScope(props.options, clientProjectId(client)),
+    ),
   }));
 }
 
@@ -170,7 +172,7 @@ export class EnhancedUploads extends Uploads {
     body: UploadCreateParams,
     options?: RequestOptions,
   ): APIPromise<WithUpload<UploadCreateResponse>> {
-    return enhanceUpload(this._client, super.create(body, options), options);
+    return enhanceUpload(this._client, super.create(body, options));
   }
 
   override retrieve(
@@ -178,7 +180,7 @@ export class EnhancedUploads extends Uploads {
     query: UploadRetrieveParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<WithUpload<UploadRetrieveResponse>> {
-    return enhanceUpload(this._client, super.retrieve(uploadID, query, options), options);
+    return enhanceUpload(this._client, super.retrieve(uploadID, query, options));
   }
 
   override triggerAction(
@@ -186,7 +188,7 @@ export class EnhancedUploads extends Uploads {
     body: UploadTriggerActionParams,
     options?: RequestOptions,
   ): APIPromise<WithUpload<UploadTriggerActionResponse>> {
-    return enhanceUpload(this._client, super.triggerAction(uploadID, body, options), options);
+    return enhanceUpload(this._client, super.triggerAction(uploadID, body, options));
   }
 
   /**

package/src/lib/workflow.ts

@@ -10,7 +10,7 @@ import {
   type WorkflowRunResponse,
 } from '../resources/workflows';
 import { type WithJob, enhanceJob } from './job';
-import { type Scope, effectiveScope, withScope } from './scope';
+import { type Scope, hasExplicitProjectId, sentScope, withScope } from './scope';
 import { validateWorkflowFlow } from './workflow_validator';
 // Type-only import to break the circular `scenario.ts` ↔ `workflow.ts` graph at runtime.
 import type { Scenario } from './scenario';
@@ -72,7 +72,10 @@ export class WorkflowEntity {
     params: WorkflowRunParams,
     options?: RequestOptions,
   ): APIPromise<WithJob<WorkflowRunResponse>> {
-    return this._client.workflows.run(this.id, params, withScope(this._scope, options));
+    // The captured scope is only a fallback: an explicit `params.projectId` or
+    // `options.query.projectId` on this call wins.
+    const scope = hasExplicitProjectId(options, params) ? undefined : this._scope;
+    return this._client.workflows.run(this.id, params, withScope(scope, options));
   }
 
   /** @internal Create a WorkflowEntity from raw workflow data, optionally remembering the originating scope. */
@@ -109,10 +112,9 @@ export class EnhancedWorkflows extends Workflows {
     options?: RequestOptions,
   ): APIPromise<EnhancedWorkflowRetrieveResponse> {
     const client = this._client as Scenario;
-    const scope = effectiveScope(options, client.projectId);
-    return super.retrieve(workflowID, query, options)._thenUnwrap((data) => ({
+    return super.retrieve(workflowID, query, options)._thenUnwrap((data, props) => ({
       ...data,
-      workflow: WorkflowEntity.from(client, data.workflow, scope),
+      workflow: WorkflowEntity.from(client, data.workflow, sentScope(props.options, client.projectId)),
     }));
   }
 
@@ -122,7 +124,7 @@ export class EnhancedWorkflows extends Workflows {
     params: WorkflowRunParams,
     options?: RequestOptions,
   ): APIPromise<WithJob<WorkflowRunResponse>> {
-    return enhanceJob(this._client, super.run(workflowID, params, options), options);
+    return enhanceJob(this._client, super.run(workflowID, params, options));
   }
 
   /** Approve a user approval node. Returns an enhanced response where `job` has `.wait()`. */
@@ -131,6 +133,6 @@ export class EnhancedWorkflows extends Workflows {
     body: WorkflowApproveUserParams,
     options?: RequestOptions,
   ): APIPromise<WithJob<WorkflowUserApprovalResponse>> {
-    return enhanceJob(this._client, super.userApproval(workflowID, body, options), options);
+    return enhanceJob(this._client, super.userApproval(workflowID, body, options));
   }
 }

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';
+}