@scenario-labs/sdk 2.4.0-alpha.1 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.4.0 (2026-06-18)
+
+Full Changelog: [v2.4.0-alpha.1...v2.4.0](https://github.com/scenario-labs/scenario-sdk-typescript/compare/v2.4.0-alpha.1...v2.4.0)
+
+### Features
+
+* **cel:** shared CEL environment with randomSample under tools namespace ([#21](https://github.com/scenario-labs/scenario-sdk-typescript/issues/21)) ([9043583](https://github.com/scenario-labs/scenario-sdk-typescript/commit/90435831e5d697b5f1b19520c088ced3b036f920))
+
 ## 2.4.0-alpha.1 (2026-06-16)
 
 Full Changelog: [v2.3.0...v2.4.0-alpha.1](https://github.com/scenario-labs/scenario-sdk-typescript/compare/v2.3.0...v2.4.0-alpha.1)

package/README.md

@@ -354,6 +354,32 @@ const client = new Scenario({
 });
 ```
 
+## Project scoping
+
+Requests can be scoped to a specific project. Pass a default `projectId` when constructing
+the client and it is sent as `?projectId=...` on every request:
+
+```ts
+import Scenario from '@scenario-labs/sdk';
+
+const client = new Scenario({ bearerAuth: jwt, projectId: 'proj_abc' });
+```
+
+This is useful with `bearerAuth` when the user belongs to multiple projects — the server
+derives the team from the project, so `teamId` doesn't need to be configured at construction
+time. With `apiKey` auth the project is already implied by the key, so this option is
+unnecessary.
+
+Override the default for a single request with `options.query.projectId`:
+
+```ts
+await client.uploads.uploadFile(params, { query: { projectId: 'proj_other' } });
+```
+
+SDK helpers (`.wait()`, `model.run()`, ...) reuse the scope effective on the originating
+call, so an action created in project A keeps polling in project A even if the client
+default changes later.
+
 ## Frequently Asked Questions
 
 ## Semantic versioning

package/lib/cel/environment.d.mts

@@ -0,0 +1,38 @@
+import { Environment } from '@marcbachmann/cel-js';
+export interface CelFunctionParam {
+    name: string;
+    description?: string;
+}
+export interface CelFunctionRegistration {
+    /** cel-js signature string, e.g. 'assetJson(string): dyn' */
+    signature: string;
+    handler: (...args: never[]) => unknown;
+    description?: string;
+    /** Parameter metadata surfaced by env.getDefinitions() (e.g. for UI palettes). */
+    params?: CelFunctionParam[];
+}
+export interface EvaluateCelOptions {
+    /** Extra functions registered for this evaluation only. */
+    functions?: CelFunctionRegistration[];
+}
+/**
+ * A fresh, extensible clone of the shared base CEL environment (trim, slice,
+ * random, randomSample). Consumers may register additional functions on it.
+ * Note: `exists()` is only available through `evaluateCel`, because it must
+ * be bound to the evaluation's variables.
+ */
+export declare function createCelEnvironment(): Environment;
+/**
+ * Canonical CEL evaluation entry point shared by the backend, frontend,
+ * and MCP server. Registers `exists(name)` bound to `variables`, plus any
+ * per-call extra functions, then evaluates.
+ *
+ * If a registered handler is async, cel-js returns a Promise — use
+ * `await evaluateCel<Promise<T>>(...)` in that case.
+ *
+ * `options.functions` must not redeclare a base function (trim, slice,
+ * random, randomSample) or `exists` — cel-js throws on overlapping
+ * signatures rather than overriding.
+ */
+export declare function evaluateCel<T = unknown>(expression: string, variables?: Record<string, unknown>, options?: EvaluateCelOptions): T;
+//# sourceMappingURL=environment.d.mts.map

package/lib/cel/environment.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.mts","sourceRoot":"","sources":["../../src/lib/cel/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAInD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAGlB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,SAAS,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACvC;AAcD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,CAElD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACvC,OAAO,GAAE,kBAAuB,GAC/B,CAAC,CAiBH"}

package/lib/cel/environment.d.ts

@@ -0,0 +1,38 @@
+import { Environment } from '@marcbachmann/cel-js';
+export interface CelFunctionParam {
+    name: string;
+    description?: string;
+}
+export interface CelFunctionRegistration {
+    /** cel-js signature string, e.g. 'assetJson(string): dyn' */
+    signature: string;
+    handler: (...args: never[]) => unknown;
+    description?: string;
+    /** Parameter metadata surfaced by env.getDefinitions() (e.g. for UI palettes). */
+    params?: CelFunctionParam[];
+}
+export interface EvaluateCelOptions {
+    /** Extra functions registered for this evaluation only. */
+    functions?: CelFunctionRegistration[];
+}
+/**
+ * A fresh, extensible clone of the shared base CEL environment (trim, slice,
+ * random, randomSample). Consumers may register additional functions on it.
+ * Note: `exists()` is only available through `evaluateCel`, because it must
+ * be bound to the evaluation's variables.
+ */
+export declare function createCelEnvironment(): Environment;
+/**
+ * Canonical CEL evaluation entry point shared by the backend, frontend,
+ * and MCP server. Registers `exists(name)` bound to `variables`, plus any
+ * per-call extra functions, then evaluates.
+ *
+ * If a registered handler is async, cel-js returns a Promise — use
+ * `await evaluateCel<Promise<T>>(...)` in that case.
+ *
+ * `options.functions` must not redeclare a base function (trim, slice,
+ * random, randomSample) or `exists` — cel-js throws on overlapping
+ * signatures rather than overriding.
+ */
+export declare function evaluateCel<T = unknown>(expression: string, variables?: Record<string, unknown>, options?: EvaluateCelOptions): T;
+//# sourceMappingURL=environment.d.ts.map

package/lib/cel/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/lib/cel/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAInD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAGlB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,SAAS,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACvC;AAcD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,CAElD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACvC,OAAO,GAAE,kBAAuB,GAC/B,CAAC,CAiBH"}

package/lib/cel/environment.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCelEnvironment = createCelEnvironment;
+exports.evaluateCel = evaluateCel;
+const cel_js_1 = require("@marcbachmann/cel-js");
+const functions_1 = require("./functions.js");
+// cel-js locks an Environment's registry the first time it is cloned: after
+// that, registerFunction on the base env throws "Cannot modify frozen
+// registry". The base env is built and populated exactly once (??= guard);
+// every createCelEnvironment() call clones the locked base, so base
+// registrations can never change after the first clone.
+let baseEnvironment;
+function getBaseEnvironment() {
+    baseEnvironment ??= (0, functions_1.registerBaseFunctions)(new cel_js_1.Environment({ unlistedVariablesAreDyn: true }));
+    return baseEnvironment;
+}
+/**
+ * A fresh, extensible clone of the shared base CEL environment (trim, slice,
+ * random, randomSample). Consumers may register additional functions on it.
+ * Note: `exists()` is only available through `evaluateCel`, because it must
+ * be bound to the evaluation's variables.
+ */
+function createCelEnvironment() {
+    return getBaseEnvironment().clone();
+}
+/**
+ * Canonical CEL evaluation entry point shared by the backend, frontend,
+ * and MCP server. Registers `exists(name)` bound to `variables`, plus any
+ * per-call extra functions, then evaluates.
+ *
+ * If a registered handler is async, cel-js returns a Promise — use
+ * `await evaluateCel<Promise<T>>(...)` in that case.
+ *
+ * `options.functions` must not redeclare a base function (trim, slice,
+ * random, randomSample) or `exists` — cel-js throws on overlapping
+ * signatures rather than overriding.
+ */
+function evaluateCel(expression, variables = {}, options = {}) {
+    const env = createCelEnvironment();
+    env.registerFunction('exists(string): bool', (name) => name in variables && variables[name] != null, {
+        description: 'True when the named variable was provided and is not null.',
+        params: [{ name: 'name', description: 'Variable name to check' }],
+    });
+    for (const fn of options.functions ?? []) {
+        env.registerFunction(fn.signature, fn.handler, {
+            ...(fn.description !== undefined ? { description: fn.description } : {}),
+            ...(fn.params !== undefined ? { params: fn.params } : {}),
+        });
+    }
+    return env.evaluate(expression, variables);
+}
+//# sourceMappingURL=environment.js.map

package/lib/cel/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/lib/cel/environment.ts"],"names":[],"mappings":";;AA2CA,oDAEC;AAcD,kCAqBC;AAhFD,iDAAmD;AAEnD,8CAAoD;AAuBpD,4EAA4E;AAC5E,sEAAsE;AACtE,2EAA2E;AAC3E,oEAAoE;AACpE,wDAAwD;AACxD,IAAI,eAAwC,CAAC;AAE7C,SAAS,kBAAkB;IACzB,eAAe,KAAK,IAAA,iCAAqB,EAAC,IAAI,oBAAW,CAAC,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9F,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB;IAClC,OAAO,kBAAkB,EAAE,CAAC,KAAK,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,WAAW,CACzB,UAAkB,EAClB,YAAqC,EAAE,EACvC,UAA8B,EAAE;IAEhC,MAAM,GAAG,GAAG,oBAAoB,EAAE,CAAC;IACnC,GAAG,CAAC,gBAAgB,CAClB,sBAAsB,EACtB,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,EAC9D;QACE,WAAW,EAAE,4DAA4D;QACzE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,wBAAwB,EAAE,CAAC;KAClE,CACF,CAAC;IACF,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;QACzC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAA0C,EAAE;YAChF,GAAG,CAAC,EAAE,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,GAAG,CAAC,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAM,CAAC;AAClD,CAAC"}

package/lib/cel/environment.mjs

@@ -0,0 +1,48 @@
+import { Environment } from '@marcbachmann/cel-js';
+import { registerBaseFunctions } from "./functions.mjs";
+// cel-js locks an Environment's registry the first time it is cloned: after
+// that, registerFunction on the base env throws "Cannot modify frozen
+// registry". The base env is built and populated exactly once (??= guard);
+// every createCelEnvironment() call clones the locked base, so base
+// registrations can never change after the first clone.
+let baseEnvironment;
+function getBaseEnvironment() {
+    baseEnvironment ??= registerBaseFunctions(new Environment({ unlistedVariablesAreDyn: true }));
+    return baseEnvironment;
+}
+/**
+ * A fresh, extensible clone of the shared base CEL environment (trim, slice,
+ * random, randomSample). Consumers may register additional functions on it.
+ * Note: `exists()` is only available through `evaluateCel`, because it must
+ * be bound to the evaluation's variables.
+ */
+export function createCelEnvironment() {
+    return getBaseEnvironment().clone();
+}
+/**
+ * Canonical CEL evaluation entry point shared by the backend, frontend,
+ * and MCP server. Registers `exists(name)` bound to `variables`, plus any
+ * per-call extra functions, then evaluates.
+ *
+ * If a registered handler is async, cel-js returns a Promise — use
+ * `await evaluateCel<Promise<T>>(...)` in that case.
+ *
+ * `options.functions` must not redeclare a base function (trim, slice,
+ * random, randomSample) or `exists` — cel-js throws on overlapping
+ * signatures rather than overriding.
+ */
+export function evaluateCel(expression, variables = {}, options = {}) {
+    const env = createCelEnvironment();
+    env.registerFunction('exists(string): bool', (name) => name in variables && variables[name] != null, {
+        description: 'True when the named variable was provided and is not null.',
+        params: [{ name: 'name', description: 'Variable name to check' }],
+    });
+    for (const fn of options.functions ?? []) {
+        env.registerFunction(fn.signature, fn.handler, {
+            ...(fn.description !== undefined ? { description: fn.description } : {}),
+            ...(fn.params !== undefined ? { params: fn.params } : {}),
+        });
+    }
+    return env.evaluate(expression, variables);
+}
+//# sourceMappingURL=environment.mjs.map

package/lib/cel/environment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.mjs","sourceRoot":"","sources":["../../src/lib/cel/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,qBAAqB,EAAE,wBAAoB;AAuBpD,4EAA4E;AAC5E,sEAAsE;AACtE,2EAA2E;AAC3E,oEAAoE;AACpE,wDAAwD;AACxD,IAAI,eAAwC,CAAC;AAE7C,SAAS,kBAAkB;IACzB,eAAe,KAAK,qBAAqB,CAAC,IAAI,WAAW,CAAC,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9F,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,kBAAkB,EAAE,CAAC,KAAK,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,UAAkB,EAClB,YAAqC,EAAE,EACvC,UAA8B,EAAE;IAEhC,MAAM,GAAG,GAAG,oBAAoB,EAAE,CAAC;IACnC,GAAG,CAAC,gBAAgB,CAClB,sBAAsB,EACtB,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,EAC9D;QACE,WAAW,EAAE,4DAA4D;QACzE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,wBAAwB,EAAE,CAAC;KAClE,CACF,CAAC;IACF,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;QACzC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAA0C,EAAE;YAChF,GAAG,CAAC,EAAE,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,GAAG,CAAC,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAM,CAAC;AAClD,CAAC"}

package/lib/cel/functions.d.mts

@@ -0,0 +1,4 @@
+import type { Environment } from '@marcbachmann/cel-js';
+/** Register the shared base functions. Order and semantics are stable API. */
+export declare function registerBaseFunctions(env: Environment): Environment;
+//# sourceMappingURL=functions.d.mts.map

package/lib/cel/functions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.mts","sourceRoot":"","sources":["../../src/lib/cel/functions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AA4CxD,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA+DnE"}

package/lib/cel/functions.d.ts

@@ -0,0 +1,4 @@
+import type { Environment } from '@marcbachmann/cel-js';
+/** Register the shared base functions. Order and semantics are stable API. */
+export declare function registerBaseFunctions(env: Environment): Environment;
+//# sourceMappingURL=functions.d.ts.map

package/lib/cel/functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../src/lib/cel/functions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AA4CxD,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA+DnE"}

package/lib/cel/functions.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBaseFunctions = registerBaseFunctions;
+const prng_1 = require("./prng.js");
+/**
+ * Random integer with exactly `digits` digits, e.g. random(5) -> 48574.
+ * Ported verbatim from the backend's cel_evaluator for back-compat with
+ * deployed workflows. Float precision degrades above 15 digits.
+ */
+function randomDigits(digits) {
+    const d = Number(digits);
+    if (d <= 0)
+        return 0n;
+    const min = 10 ** (d - 1);
+    const max = 10 ** d;
+    return BigInt(Math.floor(Math.random() * (max - min)) + min);
+}
+function randomSampleImpl(list, count, seed, withReplacement) {
+    if (!Array.isArray(list))
+        return [];
+    const rand = seed === undefined ? Math.random : (0, prng_1.mulberry32)((0, prng_1.normalizeSeed)(seed));
+    const k = Number(count);
+    return withReplacement ? (0, prng_1.sampleWithReplacement)(list, k, rand) : (0, prng_1.sampleWithoutReplacement)(list, k, rand);
+}
+const RANDOM_SAMPLE_DESCRIPTION = 'Sample items from a list. An int seed makes the result reproducible (same seed, same sample); ' +
+    'withReplacement allows duplicates. Without replacement, count is clamped to the list size.';
+const PARAM_LIST = { name: 'list', description: 'List to sample from' };
+const PARAM_COUNT = { name: 'count', description: 'Number of items to sample' };
+const PARAM_SEED = { name: 'seed', description: 'Seed for reproducible sampling' };
+const PARAM_WITH_REPLACEMENT = { name: 'withReplacement', description: 'Allow duplicate picks' };
+/** Register the shared base functions. Order and semantics are stable API. */
+function registerBaseFunctions(env) {
+    // Registered as dyn so cel-js doesn't reject null before reaching the handler.
+    env.registerFunction('trim(dyn): string', (s) => (s == null ? '' : String(s).trim()), {
+        description: 'Trim leading and trailing whitespace. Null-safe: null becomes "".',
+        params: [{ name: 'value', description: 'Value to trim; null yields ""' }],
+    });
+    // Registered as dyn first arg so cel-js doesn't reject non-list inputs before the handler.
+    env.registerFunction('slice(dyn, int, int): list', (arr, start, end) => {
+        if (!Array.isArray(arr))
+            return [];
+        return arr.slice(Number(start), Number(end));
+    }, {
+        description: 'Return list[start:end] with JS Array.prototype.slice semantics.',
+        params: [
+            { name: 'list', description: 'List to slice' },
+            { name: 'start', description: 'Start index (inclusive)' },
+            { name: 'end', description: 'End index (exclusive)' },
+        ],
+    });
+    env.registerFunction('random(int): int', (digits) => randomDigits(digits), {
+        description: 'Random integer with exactly N digits, e.g. random(5) -> 48574. Unseeded.',
+        params: [{ name: 'digits', description: 'Number of digits in the result' }],
+    });
+    env.registerFunction('randomSample(list, int): list', (list, count) => randomSampleImpl(list, count, undefined, false), { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT] });
+    env.registerFunction('randomSample(list, int, int): list', (list, count, seed) => randomSampleImpl(list, count, seed, false), { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED] });
+    env.registerFunction('randomSample(list, int, bool): list', (list, count, withReplacement) => randomSampleImpl(list, count, undefined, withReplacement), {
+        description: RANDOM_SAMPLE_DESCRIPTION,
+        params: [PARAM_LIST, PARAM_COUNT, PARAM_WITH_REPLACEMENT],
+    });
+    env.registerFunction('randomSample(list, int, int, bool): list', (list, count, seed, withReplacement) => randomSampleImpl(list, count, seed, withReplacement), {
+        description: RANDOM_SAMPLE_DESCRIPTION,
+        params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED, PARAM_WITH_REPLACEMENT],
+    });
+    return env;
+}
+//# sourceMappingURL=functions.js.map

package/lib/cel/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../../src/lib/cel/functions.ts"],"names":[],"mappings":"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"}

package/lib/cel/functions.mjs

@@ -0,0 +1,64 @@
+import { mulberry32, normalizeSeed, sampleWithoutReplacement, sampleWithReplacement, } from "./prng.mjs";
+/**
+ * Random integer with exactly `digits` digits, e.g. random(5) -> 48574.
+ * Ported verbatim from the backend's cel_evaluator for back-compat with
+ * deployed workflows. Float precision degrades above 15 digits.
+ */
+function randomDigits(digits) {
+    const d = Number(digits);
+    if (d <= 0)
+        return 0n;
+    const min = 10 ** (d - 1);
+    const max = 10 ** d;
+    return BigInt(Math.floor(Math.random() * (max - min)) + min);
+}
+function randomSampleImpl(list, count, seed, withReplacement) {
+    if (!Array.isArray(list))
+        return [];
+    const rand = seed === undefined ? Math.random : mulberry32(normalizeSeed(seed));
+    const k = Number(count);
+    return withReplacement ? sampleWithReplacement(list, k, rand) : sampleWithoutReplacement(list, k, rand);
+}
+const RANDOM_SAMPLE_DESCRIPTION = 'Sample items from a list. An int seed makes the result reproducible (same seed, same sample); ' +
+    'withReplacement allows duplicates. Without replacement, count is clamped to the list size.';
+const PARAM_LIST = { name: 'list', description: 'List to sample from' };
+const PARAM_COUNT = { name: 'count', description: 'Number of items to sample' };
+const PARAM_SEED = { name: 'seed', description: 'Seed for reproducible sampling' };
+const PARAM_WITH_REPLACEMENT = { name: 'withReplacement', description: 'Allow duplicate picks' };
+/** Register the shared base functions. Order and semantics are stable API. */
+export function registerBaseFunctions(env) {
+    // Registered as dyn so cel-js doesn't reject null before reaching the handler.
+    env.registerFunction('trim(dyn): string', (s) => (s == null ? '' : String(s).trim()), {
+        description: 'Trim leading and trailing whitespace. Null-safe: null becomes "".',
+        params: [{ name: 'value', description: 'Value to trim; null yields ""' }],
+    });
+    // Registered as dyn first arg so cel-js doesn't reject non-list inputs before the handler.
+    env.registerFunction('slice(dyn, int, int): list', (arr, start, end) => {
+        if (!Array.isArray(arr))
+            return [];
+        return arr.slice(Number(start), Number(end));
+    }, {
+        description: 'Return list[start:end] with JS Array.prototype.slice semantics.',
+        params: [
+            { name: 'list', description: 'List to slice' },
+            { name: 'start', description: 'Start index (inclusive)' },
+            { name: 'end', description: 'End index (exclusive)' },
+        ],
+    });
+    env.registerFunction('random(int): int', (digits) => randomDigits(digits), {
+        description: 'Random integer with exactly N digits, e.g. random(5) -> 48574. Unseeded.',
+        params: [{ name: 'digits', description: 'Number of digits in the result' }],
+    });
+    env.registerFunction('randomSample(list, int): list', (list, count) => randomSampleImpl(list, count, undefined, false), { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT] });
+    env.registerFunction('randomSample(list, int, int): list', (list, count, seed) => randomSampleImpl(list, count, seed, false), { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED] });
+    env.registerFunction('randomSample(list, int, bool): list', (list, count, withReplacement) => randomSampleImpl(list, count, undefined, withReplacement), {
+        description: RANDOM_SAMPLE_DESCRIPTION,
+        params: [PARAM_LIST, PARAM_COUNT, PARAM_WITH_REPLACEMENT],
+    });
+    env.registerFunction('randomSample(list, int, int, bool): list', (list, count, seed, withReplacement) => randomSampleImpl(list, count, seed, withReplacement), {
+        description: RANDOM_SAMPLE_DESCRIPTION,
+        params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED, PARAM_WITH_REPLACEMENT],
+    });
+    return env;
+}
+//# sourceMappingURL=functions.mjs.map

package/lib/cel/functions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.mjs","sourceRoot":"","sources":["../../src/lib/cel/functions.ts"],"names":[],"mappings":"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"}

package/lib/cel/index.d.mts

@@ -0,0 +1,3 @@
+export { createCelEnvironment, evaluateCel, type CelFunctionParam, type CelFunctionRegistration, type EvaluateCelOptions, } from "./environment.mjs";
+export { Environment } from '@marcbachmann/cel-js';
+//# sourceMappingURL=index.d.mts.map

package/lib/cel/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/lib/cel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,0BAAsB;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/cel/index.d.ts

@@ -0,0 +1,3 @@
+export { createCelEnvironment, evaluateCel, type CelFunctionParam, type CelFunctionRegistration, type EvaluateCelOptions, } from "./environment.js";
+export { Environment } from '@marcbachmann/cel-js';
+//# sourceMappingURL=index.d.ts.map

package/lib/cel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/cel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,yBAAsB;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/cel/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Environment = exports.evaluateCel = exports.createCelEnvironment = void 0;
+var environment_1 = require("./environment.js");
+Object.defineProperty(exports, "createCelEnvironment", { enumerable: true, get: function () { return environment_1.createCelEnvironment; } });
+Object.defineProperty(exports, "evaluateCel", { enumerable: true, get: function () { return environment_1.evaluateCel; } });
+var cel_js_1 = require("@marcbachmann/cel-js");
+Object.defineProperty(exports, "Environment", { enumerable: true, get: function () { return cel_js_1.Environment; } });
+//# sourceMappingURL=index.js.map

package/lib/cel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/cel/index.ts"],"names":[],"mappings":";;;AAAA,gDAMuB;AALrB,mHAAA,oBAAoB,OAAA;AACpB,0GAAA,WAAW,OAAA;AAKb,+CAAmD;AAA1C,qGAAA,WAAW,OAAA"}

package/lib/cel/index.mjs

@@ -0,0 +1,3 @@
+export { createCelEnvironment, evaluateCel, } from "./environment.mjs";
+export { Environment } from '@marcbachmann/cel-js';
+//# sourceMappingURL=index.mjs.map

package/lib/cel/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/lib/cel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,WAAW,GAIZ,0BAAsB;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/cel/prng.d.mts

@@ -0,0 +1,28 @@
+/**
+ * Deterministic PRNG + sampling primitives backing the CEL `randomSample`
+ * function.
+ *
+ * STABILITY CONTRACT — DO NOT CHANGE THESE ALGORITHMS.
+ * The same seed must produce the same sample on every runtime and every SDK
+ * version: the backend (server) and frontend (client) rely on agreeing outputs,
+ * and customers rely on seeds for reproducible workflow runs. Golden-value
+ * tests in tests/lib/cel/prng.test.ts pin the exact outputs.
+ */
+/** A source of random floats in [0, 1). */
+export type RandomSource = () => number;
+/**
+ * mulberry32: fast 32-bit PRNG with exact, platform-independent output.
+ * `seed` is coerced to uint32 (via `>>> 0`); use {@link normalizeSeed} to
+ * convert arbitrary CEL ints before calling this.
+ */
+export declare function mulberry32(seed: number): RandomSource;
+/** Normalize a CEL int (bigint or number) to a uint32 PRNG seed. */
+export declare function normalizeSeed(seed: bigint | number): number;
+/**
+ * Sample `count` distinct elements via partial Fisher–Yates.
+ * `count` is clamped to [0, list.length]; the input list is not mutated.
+ */
+export declare function sampleWithoutReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[];
+/** `count` independent draws; duplicates allowed. Returns [] if the list is empty or count <= 0. */
+export declare function sampleWithReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[];
+//# sourceMappingURL=prng.d.mts.map

package/lib/cel/prng.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prng.d.mts","sourceRoot":"","sources":["../../src/lib/cel/prng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAQrD;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,CAAC,EAAE,CAYtG;AAED,oGAAoG;AACpG,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,CAAC,EAAE,CAQnG"}

package/lib/cel/prng.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Deterministic PRNG + sampling primitives backing the CEL `randomSample`
+ * function.
+ *
+ * STABILITY CONTRACT — DO NOT CHANGE THESE ALGORITHMS.
+ * The same seed must produce the same sample on every runtime and every SDK
+ * version: the backend (server) and frontend (client) rely on agreeing outputs,
+ * and customers rely on seeds for reproducible workflow runs. Golden-value
+ * tests in tests/lib/cel/prng.test.ts pin the exact outputs.
+ */
+/** A source of random floats in [0, 1). */
+export type RandomSource = () => number;
+/**
+ * mulberry32: fast 32-bit PRNG with exact, platform-independent output.
+ * `seed` is coerced to uint32 (via `>>> 0`); use {@link normalizeSeed} to
+ * convert arbitrary CEL ints before calling this.
+ */
+export declare function mulberry32(seed: number): RandomSource;
+/** Normalize a CEL int (bigint or number) to a uint32 PRNG seed. */
+export declare function normalizeSeed(seed: bigint | number): number;
+/**
+ * Sample `count` distinct elements via partial Fisher–Yates.
+ * `count` is clamped to [0, list.length]; the input list is not mutated.
+ */
+export declare function sampleWithoutReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[];
+/** `count` independent draws; duplicates allowed. Returns [] if the list is empty or count <= 0. */
+export declare function sampleWithReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[];
+//# sourceMappingURL=prng.d.ts.map

package/lib/cel/prng.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prng.d.ts","sourceRoot":"","sources":["../../src/lib/cel/prng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAQrD;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,CAAC,EAAE,CAYtG;AAED,oGAAoG;AACpG,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,CAAC,EAAE,CAQnG"}

package/lib/cel/prng.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Deterministic PRNG + sampling primitives backing the CEL `randomSample`
+ * function.
+ *
+ * STABILITY CONTRACT — DO NOT CHANGE THESE ALGORITHMS.
+ * The same seed must produce the same sample on every runtime and every SDK
+ * version: the backend (server) and frontend (client) rely on agreeing outputs,
+ * and customers rely on seeds for reproducible workflow runs. Golden-value
+ * tests in tests/lib/cel/prng.test.ts pin the exact outputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mulberry32 = mulberry32;
+exports.normalizeSeed = normalizeSeed;
+exports.sampleWithoutReplacement = sampleWithoutReplacement;
+exports.sampleWithReplacement = sampleWithReplacement;
+/**
+ * mulberry32: fast 32-bit PRNG with exact, platform-independent output.
+ * `seed` is coerced to uint32 (via `>>> 0`); use {@link normalizeSeed} to
+ * convert arbitrary CEL ints before calling this.
+ */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Normalize a CEL int (bigint or number) to a uint32 PRNG seed. */
+function normalizeSeed(seed) {
+    return Number(BigInt.asUintN(32, BigInt(seed)));
+}
+/**
+ * Sample `count` distinct elements via partial Fisher–Yates.
+ * `count` is clamped to [0, list.length]; the input list is not mutated.
+ */
+function sampleWithoutReplacement(list, count, rand) {
+    const n = list.length;
+    const k = Math.min(Math.max(count, 0), n);
+    if (k === 0)
+        return [];
+    const pool = list.slice();
+    for (let i = 0; i < k; i++) {
+        const j = i + Math.floor(rand() * (n - i));
+        const tmp = pool[i];
+        pool[i] = pool[j];
+        pool[j] = tmp;
+    }
+    return pool.slice(0, k);
+}
+/** `count` independent draws; duplicates allowed. Returns [] if the list is empty or count <= 0. */
+function sampleWithReplacement(list, count, rand) {
+    const n = list.length;
+    if (n === 0 || count <= 0)
+        return [];
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        out.push(list[Math.floor(rand() * n)]);
+    }
+    return out;
+}
+//# sourceMappingURL=prng.js.map

package/lib/cel/prng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prng.js","sourceRoot":"","sources":["../../src/lib/cel/prng.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAUH,gCAQC;AAGD,sCAEC;AAMD,4DAYC;AAGD,sDAQC;AA/CD;;;;GAIG;AACH,SAAgB,UAAU,CAAC,IAAY;IACrC,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;IACnB,OAAO,GAAG,EAAE;QACV,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,SAAgB,aAAa,CAAC,IAAqB;IACjD,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAI,IAAkB,EAAE,KAAa,EAAE,IAAkB;IAC/F,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACnB,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED,oGAAoG;AACpG,SAAgB,qBAAqB,CAAI,IAAkB,EAAE,KAAa,EAAE,IAAkB;IAC5F,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/lib/cel/prng.mjs

@@ -0,0 +1,58 @@
+/**
+ * Deterministic PRNG + sampling primitives backing the CEL `randomSample`
+ * function.
+ *
+ * STABILITY CONTRACT — DO NOT CHANGE THESE ALGORITHMS.
+ * The same seed must produce the same sample on every runtime and every SDK
+ * version: the backend (server) and frontend (client) rely on agreeing outputs,
+ * and customers rely on seeds for reproducible workflow runs. Golden-value
+ * tests in tests/lib/cel/prng.test.ts pin the exact outputs.
+ */
+/**
+ * mulberry32: fast 32-bit PRNG with exact, platform-independent output.
+ * `seed` is coerced to uint32 (via `>>> 0`); use {@link normalizeSeed} to
+ * convert arbitrary CEL ints before calling this.
+ */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Normalize a CEL int (bigint or number) to a uint32 PRNG seed. */
+export function normalizeSeed(seed) {
+    return Number(BigInt.asUintN(32, BigInt(seed)));
+}
+/**
+ * Sample `count` distinct elements via partial Fisher–Yates.
+ * `count` is clamped to [0, list.length]; the input list is not mutated.
+ */
+export function sampleWithoutReplacement(list, count, rand) {
+    const n = list.length;
+    const k = Math.min(Math.max(count, 0), n);
+    if (k === 0)
+        return [];
+    const pool = list.slice();
+    for (let i = 0; i < k; i++) {
+        const j = i + Math.floor(rand() * (n - i));
+        const tmp = pool[i];
+        pool[i] = pool[j];
+        pool[j] = tmp;
+    }
+    return pool.slice(0, k);
+}
+/** `count` independent draws; duplicates allowed. Returns [] if the list is empty or count <= 0. */
+export function sampleWithReplacement(list, count, rand) {
+    const n = list.length;
+    if (n === 0 || count <= 0)
+        return [];
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        out.push(list[Math.floor(rand() * n)]);
+    }
+    return out;
+}
+//# sourceMappingURL=prng.mjs.map

package/lib/cel/prng.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prng.mjs","sourceRoot":"","sources":["../../src/lib/cel/prng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;IACnB,OAAO,GAAG,EAAE;QACV,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAAC,IAAqB;IACjD,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAI,IAAkB,EAAE,KAAa,EAAE,IAAkB;IAC/F,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACnB,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,qBAAqB,CAAI,IAAkB,EAAE,KAAa,EAAE,IAAkB;IAC5F,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenario-labs/sdk",
-  "version": "2.4.0-alpha.1",
+  "version": "2.4.0",
   "description": "The official TypeScript library for the Scenario API",
   "author": "Scenario <support@scenario.com>",
   "types": "./index.d.ts",
@@ -8,6 +8,9 @@
   "type": "commonjs",
   "repository": "github:scenario-labs/scenario-sdk-typescript",
   "license": "MIT",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
   "files": [
     "**/*"
   ],
@@ -15,7 +18,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@marcbachmann/cel-js": "^7.6.1"
+  },
   "overrides": {
     "minimatch": "^9.0.7",
     "handlebars": "^4.7.9",
@@ -137,6 +142,16 @@
     "./resources.mjs": {
       "default": "./resources.mjs"
     },
+    "./tools/*.mjs": {
+      "default": "./tools/*.mjs"
+    },
+    "./tools/*.js": {
+      "default": "./tools/*.js"
+    },
+    "./tools/*": {
+      "import": "./tools/*.mjs",
+      "require": "./tools/*.js"
+    },
     "./uploads": {
       "import": "./uploads.mjs",
       "require": "./uploads.js"

package/src/lib/cel/environment.ts

@@ -0,0 +1,81 @@
+import { Environment } from '@marcbachmann/cel-js';
+
+import { registerBaseFunctions } from './functions';
+
+export interface CelFunctionParam {
+  name: string;
+  description?: string;
+}
+
+export interface CelFunctionRegistration {
+  /** cel-js signature string, e.g. 'assetJson(string): dyn' */
+  signature: string;
+  // never[] rest params make any typed handler assignable without casts
+  // (parameter contravariance); unknown[] would reject e.g. (id: string) => x.
+  handler: (...args: never[]) => unknown;
+  description?: string;
+  /** Parameter metadata surfaced by env.getDefinitions() (e.g. for UI palettes). */
+  params?: CelFunctionParam[];
+}
+
+export interface EvaluateCelOptions {
+  /** Extra functions registered for this evaluation only. */
+  functions?: CelFunctionRegistration[];
+}
+
+// cel-js locks an Environment's registry the first time it is cloned: after
+// that, registerFunction on the base env throws "Cannot modify frozen
+// registry". The base env is built and populated exactly once (??= guard);
+// every createCelEnvironment() call clones the locked base, so base
+// registrations can never change after the first clone.
+let baseEnvironment: Environment | undefined;
+
+function getBaseEnvironment(): Environment {
+  baseEnvironment ??= registerBaseFunctions(new Environment({ unlistedVariablesAreDyn: true }));
+  return baseEnvironment;
+}
+
+/**
+ * A fresh, extensible clone of the shared base CEL environment (trim, slice,
+ * random, randomSample). Consumers may register additional functions on it.
+ * Note: `exists()` is only available through `evaluateCel`, because it must
+ * be bound to the evaluation's variables.
+ */
+export function createCelEnvironment(): Environment {
+  return getBaseEnvironment().clone();
+}
+
+/**
+ * Canonical CEL evaluation entry point shared by the backend, frontend,
+ * and MCP server. Registers `exists(name)` bound to `variables`, plus any
+ * per-call extra functions, then evaluates.
+ *
+ * If a registered handler is async, cel-js returns a Promise — use
+ * `await evaluateCel<Promise<T>>(...)` in that case.
+ *
+ * `options.functions` must not redeclare a base function (trim, slice,
+ * random, randomSample) or `exists` — cel-js throws on overlapping
+ * signatures rather than overriding.
+ */
+export function evaluateCel<T = unknown>(
+  expression: string,
+  variables: Record<string, unknown> = {},
+  options: EvaluateCelOptions = {},
+): T {
+  const env = createCelEnvironment();
+  env.registerFunction(
+    'exists(string): bool',
+    (name: string) => name in variables && variables[name] != null,
+    {
+      description: 'True when the named variable was provided and is not null.',
+      params: [{ name: 'name', description: 'Variable name to check' }],
+    },
+  );
+  for (const fn of options.functions ?? []) {
+    env.registerFunction(fn.signature, fn.handler as (...args: unknown[]) => unknown, {
+      ...(fn.description !== undefined ? { description: fn.description } : {}),
+      ...(fn.params !== undefined ? { params: fn.params } : {}),
+    });
+  }
+  return env.evaluate(expression, variables) as T;
+}

package/src/lib/cel/functions.ts

@@ -0,0 +1,109 @@
+import type { Environment } from '@marcbachmann/cel-js';
+
+import {
+  mulberry32,
+  normalizeSeed,
+  sampleWithoutReplacement,
+  sampleWithReplacement,
+  type RandomSource,
+} from './prng';
+
+/**
+ * Random integer with exactly `digits` digits, e.g. random(5) -> 48574.
+ * Ported verbatim from the backend's cel_evaluator for back-compat with
+ * deployed workflows. Float precision degrades above 15 digits.
+ */
+function randomDigits(digits: bigint | number): bigint {
+  const d = Number(digits);
+  if (d <= 0) return 0n;
+  const min = 10 ** (d - 1);
+  const max = 10 ** d;
+  return BigInt(Math.floor(Math.random() * (max - min)) + min);
+}
+
+function randomSampleImpl(
+  list: unknown,
+  count: bigint | number,
+  seed: bigint | number | undefined,
+  withReplacement: boolean,
+): unknown[] {
+  if (!Array.isArray(list)) return [];
+  const rand: RandomSource = seed === undefined ? Math.random : mulberry32(normalizeSeed(seed));
+  const k = Number(count);
+  return withReplacement ? sampleWithReplacement(list, k, rand) : sampleWithoutReplacement(list, k, rand);
+}
+
+const RANDOM_SAMPLE_DESCRIPTION =
+  'Sample items from a list. An int seed makes the result reproducible (same seed, same sample); ' +
+  'withReplacement allows duplicates. Without replacement, count is clamped to the list size.';
+
+const PARAM_LIST = { name: 'list', description: 'List to sample from' };
+const PARAM_COUNT = { name: 'count', description: 'Number of items to sample' };
+const PARAM_SEED = { name: 'seed', description: 'Seed for reproducible sampling' };
+const PARAM_WITH_REPLACEMENT = { name: 'withReplacement', description: 'Allow duplicate picks' };
+
+/** Register the shared base functions. Order and semantics are stable API. */
+export function registerBaseFunctions(env: Environment): Environment {
+  // Registered as dyn so cel-js doesn't reject null before reaching the handler.
+  env.registerFunction('trim(dyn): string', (s: string) => (s == null ? '' : String(s).trim()), {
+    description: 'Trim leading and trailing whitespace. Null-safe: null becomes "".',
+    params: [{ name: 'value', description: 'Value to trim; null yields ""' }],
+  });
+
+  // Registered as dyn first arg so cel-js doesn't reject non-list inputs before the handler.
+  env.registerFunction(
+    'slice(dyn, int, int): list',
+    (arr: unknown, start: bigint | number, end: bigint | number) => {
+      if (!Array.isArray(arr)) return [];
+      return arr.slice(Number(start), Number(end));
+    },
+    {
+      description: 'Return list[start:end] with JS Array.prototype.slice semantics.',
+      params: [
+        { name: 'list', description: 'List to slice' },
+        { name: 'start', description: 'Start index (inclusive)' },
+        { name: 'end', description: 'End index (exclusive)' },
+      ],
+    },
+  );
+
+  env.registerFunction('random(int): int', (digits: bigint | number) => randomDigits(digits), {
+    description: 'Random integer with exactly N digits, e.g. random(5) -> 48574. Unseeded.',
+    params: [{ name: 'digits', description: 'Number of digits in the result' }],
+  });
+
+  env.registerFunction(
+    'randomSample(list, int): list',
+    (list: unknown, count: bigint | number) => randomSampleImpl(list, count, undefined, false),
+    { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT] },
+  );
+
+  env.registerFunction(
+    'randomSample(list, int, int): list',
+    (list: unknown, count: bigint | number, seed: bigint | number) =>
+      randomSampleImpl(list, count, seed, false),
+    { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED] },
+  );
+
+  env.registerFunction(
+    'randomSample(list, int, bool): list',
+    (list: unknown, count: bigint | number, withReplacement: boolean) =>
+      randomSampleImpl(list, count, undefined, withReplacement),
+    {
+      description: RANDOM_SAMPLE_DESCRIPTION,
+      params: [PARAM_LIST, PARAM_COUNT, PARAM_WITH_REPLACEMENT],
+    },
+  );
+
+  env.registerFunction(
+    'randomSample(list, int, int, bool): list',
+    (list: unknown, count: bigint | number, seed: bigint | number, withReplacement: boolean) =>
+      randomSampleImpl(list, count, seed, withReplacement),
+    {
+      description: RANDOM_SAMPLE_DESCRIPTION,
+      params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED, PARAM_WITH_REPLACEMENT],
+    },
+  );
+
+  return env;
+}

package/src/lib/cel/index.ts

@@ -0,0 +1,8 @@
+export {
+  createCelEnvironment,
+  evaluateCel,
+  type CelFunctionParam,
+  type CelFunctionRegistration,
+  type EvaluateCelOptions,
+} from './environment';
+export { Environment } from '@marcbachmann/cel-js';

package/src/lib/cel/prng.ts

@@ -0,0 +1,62 @@
+/**
+ * Deterministic PRNG + sampling primitives backing the CEL `randomSample`
+ * function.
+ *
+ * STABILITY CONTRACT — DO NOT CHANGE THESE ALGORITHMS.
+ * The same seed must produce the same sample on every runtime and every SDK
+ * version: the backend (server) and frontend (client) rely on agreeing outputs,
+ * and customers rely on seeds for reproducible workflow runs. Golden-value
+ * tests in tests/lib/cel/prng.test.ts pin the exact outputs.
+ */
+
+/** A source of random floats in [0, 1). */
+export type RandomSource = () => number;
+
+/**
+ * mulberry32: fast 32-bit PRNG with exact, platform-independent output.
+ * `seed` is coerced to uint32 (via `>>> 0`); use {@link normalizeSeed} to
+ * convert arbitrary CEL ints before calling this.
+ */
+export function mulberry32(seed: number): RandomSource {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Normalize a CEL int (bigint or number) to a uint32 PRNG seed. */
+export function normalizeSeed(seed: bigint | number): number {
+  return Number(BigInt.asUintN(32, BigInt(seed)));
+}
+
+/**
+ * Sample `count` distinct elements via partial Fisher–Yates.
+ * `count` is clamped to [0, list.length]; the input list is not mutated.
+ */
+export function sampleWithoutReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[] {
+  const n = list.length;
+  const k = Math.min(Math.max(count, 0), n);
+  if (k === 0) return [];
+  const pool = list.slice();
+  for (let i = 0; i < k; i++) {
+    const j = i + Math.floor(rand() * (n - i));
+    const tmp = pool[i]!;
+    pool[i] = pool[j]!;
+    pool[j] = tmp;
+  }
+  return pool.slice(0, k);
+}
+
+/** `count` independent draws; duplicates allowed. Returns [] if the list is empty or count <= 0. */
+export function sampleWithReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[] {
+  const n = list.length;
+  if (n === 0 || count <= 0) return [];
+  const out: T[] = [];
+  for (let i = 0; i < count; i++) {
+    out.push(list[Math.floor(rand() * n)]!);
+  }
+  return out;
+}

package/src/tools/cel.ts

@@ -0,0 +1,4 @@
+// Public "tools" namespace: import from '@scenario-labs/sdk/tools/cel'.
+// Implementation lives in src/lib/cel/ (the Stainless generator never
+// modifies src/lib/); this shim only defines the public import path.
+export * from '../lib/cel/index';

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '2.4.0-alpha.1'; // x-release-please-version
+export const VERSION = '2.4.0'; // x-release-please-version

package/tools/cel.d.mts

@@ -0,0 +1,2 @@
+export * from "../lib/cel/index.mjs";
+//# sourceMappingURL=cel.d.mts.map

package/tools/cel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel.d.mts","sourceRoot":"","sources":["../src/tools/cel.ts"],"names":[],"mappings":"AAGA,qCAAiC"}

package/tools/cel.d.ts

@@ -0,0 +1,2 @@
+export * from "../lib/cel/index.js";
+//# sourceMappingURL=cel.d.ts.map

package/tools/cel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../src/tools/cel.ts"],"names":[],"mappings":"AAGA,oCAAiC"}

package/tools/cel.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("../internal/tslib.js");
+// Public "tools" namespace: import from '@scenario-labs/sdk/tools/cel'.
+// Implementation lives in src/lib/cel/ (the Stainless generator never
+// modifies src/lib/); this shim only defines the public import path.
+tslib_1.__exportStar(require("../lib/cel/index.js"), exports);
+//# sourceMappingURL=cel.js.map

package/tools/cel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel.js","sourceRoot":"","sources":["../src/tools/cel.ts"],"names":[],"mappings":";;;AAAA,wEAAwE;AACxE,sEAAsE;AACtE,qEAAqE;AACrE,8DAAiC"}

package/tools/cel.mjs

@@ -0,0 +1,5 @@
+// Public "tools" namespace: import from '@scenario-labs/sdk/tools/cel'.
+// Implementation lives in src/lib/cel/ (the Stainless generator never
+// modifies src/lib/); this shim only defines the public import path.
+export * from "../lib/cel/index.mjs";
+//# sourceMappingURL=cel.mjs.map

package/tools/cel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel.mjs","sourceRoot":"","sources":["../src/tools/cel.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,sEAAsE;AACtE,qEAAqE;AACrE,qCAAiC"}

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.4.0-alpha.1";
+export declare const VERSION = "2.4.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.4.0-alpha.1";
+export declare const VERSION = "2.4.0";
 //# sourceMappingURL=version.d.ts.map

package/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '2.4.0-alpha.1'; // x-release-please-version
+exports.VERSION = '2.4.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,eAAe,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,OAAO,CAAC,CAAC,2BAA2B"}

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '2.4.0-alpha.1'; // x-release-please-version
+export const VERSION = '2.4.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map

package/version.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,2BAA2B"}