@olib-ai/owl-browser-sdk 2.0.7 → 2.1.0

package/dist/flow/executor.js

@@ -6,9 +6,64 @@
  */
 import * as fs from 'node:fs';
 import { ConditionOperator } from '../types.js';
-import { resolveVariables } from './variables.js';
+import { resolveValue, resolveVariables } from './variables.js';
 import { checkExpectation } from './expectations.js';
 import { evaluateCondition } from './conditions.js';
+import { applyExtract } from './extraction.js';
+import { makeEvent } from './notifications.js';
+class TimeoutAbort extends Error {
+    constructor() {
+        super('step timeout');
+        this.name = 'TimeoutAbort';
+    }
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((r) => setTimeout(r, ms));
+}
+function retryDelayMs(attempt, baseMs, maxMs) {
+    if (baseMs <= 0)
+        return 0;
+    let delay = baseMs * Math.pow(2, attempt);
+    if (maxMs > 0 && delay > maxMs)
+        delay = maxMs;
+    return delay;
+}
+/**
+ * Resolve any ${prev}/${vars}/${params} references inside an expectation
+ * payload. Returns a new StepExpectation with string fields run through
+ * the resolver; numeric/boolean fields are passed through unchanged.
+ */
+function resolveExpectation(expected, previousResult, vars_, params_) {
+    const resolved = { ...expected };
+    if (expected.equals !== undefined) {
+        resolved.equals = resolveValue(expected.equals, previousResult, vars_, params_);
+    }
+    if (expected.contains !== undefined) {
+        resolved.contains = resolveValue(expected.contains, previousResult, vars_, params_);
+    }
+    if (expected.matches !== undefined) {
+        resolved.matches = resolveValue(expected.matches, previousResult, vars_, params_);
+    }
+    if (expected.oneOf !== undefined) {
+        resolved.oneOf = resolveValue(expected.oneOf, previousResult, vars_, params_);
+    }
+    return resolved;
+}
+async function runWithTimeout(fn, timeoutMs) {
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new TimeoutAbort()), timeoutMs);
+    });
+    try {
+        return await Promise.race([fn(), timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Parameter aliases for flow JSON compatibility.
  * Maps tool_name -> {alias_name -> canonical_name}
@@ -52,12 +107,6 @@ function applyParameterAliases(toolName, params) {
 function generateStepId() {
     return 'step_' + Math.random().toString(36).substring(2, 10);
 }
-/**
- * Sleep for a given number of milliseconds.
- */
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
 /**
  * Flow execution engine that runs a series of browser tool steps.
  *
@@ -92,9 +141,31 @@ export class FlowExecutor {
     _client;
     _contextId;
     _abortFlag = false;
-    constructor(client, contextId) {
+    /**
+     * Flow-scoped variables captured by `step.capture = "name"`. Resolved via
+     * `${vars.NAME}` in any later step's params, regardless of how many
+     * steps separate the capture from the use.
+     */
+    _vars = {};
+    /**
+     * Flow-scoped read-only parameters. Seeded from `flow.parameters`, may be
+     * overridden via setParams() (runner CLI). Resolved via `${params.NAME}`.
+     */
+    _params = {};
+    _notifier;
+    _eventMetadata = {};
+    constructor(client, contextId, options) {
         this._client = client;
         this._contextId = contextId;
+        this._notifier = options?.notifier;
+    }
+    /** Attach metadata to every FlowEvent this executor emits. */
+    setEventMetadata(metadata) {
+        this._eventMetadata = { ...metadata };
+    }
+    /** Override flow parameters; merged with declared defaults at execute() time. */
+    setParams(params) {
+        Object.assign(this._params, params);
     }
     /**
      * Signal to abort the current flow execution.
@@ -103,42 +174,140 @@ export class FlowExecutor {
         this._abortFlag = true;
     }
     /**
-     * Reset the abort flag for a new execution.
+     * Reset the abort flag and clear flow-scoped vars for a new execution.
      */
     reset() {
         this._abortFlag = false;
+        this._vars = {};
+        this._params = {};
     }
     /**
      * Execute a flow and return the results.
+     *
+     * Honours the flow's top-level `requiredEnv` and `timeoutSeconds`
+     * directly — embedders that drive `FlowExecutor` from their own code
+     * get the same gates the bundled runner provides, without having to
+     * reimplement them. When `requiredEnv` is unmet, the executor returns
+     * `success: true, skipped: true` and emits `flow.skipped` (no
+     * `flow.started` is emitted in that case so subscribers never see a
+     * started event without a terminal counterpart).
      */
     async execute(flow) {
         this._abortFlag = false;
+        this._vars = {};
+        // Seed parameter scope: flow defaults first, then any setParams() overrides.
+        const merged = { ...(flow.parameters ?? {}), ...this._params };
+        this._params = merged;
         const startTime = performance.now();
         const results = [];
-        const enabledSteps = flow.steps.filter(s => s.enabled);
-        if (enabledSteps.length === 0) {
-            return {
+        // Pre-flight: requiredEnv. If any declared env var is missing or
+        // empty, skip the flow with a clean reason instead of running it
+        // blind and failing mid-step. Emit `flow.skipped`; no `flow.started`
+        // first because there's no terminal event to pair with.
+        const missingEnv = (flow.requiredEnv ?? []).filter((n) => !process.env[n]);
+        if (missingEnv.length > 0) {
+            const reason = `missing required env vars: ${missingEnv.join(', ')}`;
+            const skipped = {
                 success: true,
                 steps: [],
                 totalDurationMs: 0,
+                error: reason,
+                skipped: true,
             };
+            await this._emitSkipped(flow, reason);
+            return skipped;
+        }
+        await this._emitStarted(flow);
+        const enabledSteps = flow.steps.filter(s => s.enabled);
+        if (enabledSteps.length === 0) {
+            const empty = { success: true, steps: [], totalDurationMs: 0 };
+            await this._emitTerminal(flow, empty, startTime);
+            return empty;
         }
+        // Wall-clock cap for the entire flow. When the flow declares
+        // `timeoutSeconds` we race the step-loop against a timer. The
+        // bundled runner has its own outer cap; embedders calling execute()
+        // directly would otherwise have no cap.
+        const timeoutS = flow.timeoutSeconds && flow.timeoutSeconds > 0
+            ? flow.timeoutSeconds : undefined;
+        let final;
         try {
-            const [success] = await this._executeSteps(enabledSteps, results, undefined);
-            return {
+            let success;
+            if (timeoutS !== undefined) {
+                const [ok] = await runWithTimeout(() => this._executeSteps(enabledSteps, results, undefined), timeoutS * 1000);
+                success = ok;
+            }
+            else {
+                const [ok] = await this._executeSteps(enabledSteps, results, undefined);
+                success = ok;
+            }
+            final = {
                 success,
                 steps: results,
                 totalDurationMs: performance.now() - startTime,
             };
         }
         catch (e) {
-            return {
+            const isTimeout = e instanceof TimeoutAbort;
+            final = {
                 success: false,
                 steps: results,
                 totalDurationMs: performance.now() - startTime,
-                error: e instanceof Error ? e.message : String(e),
+                error: isTimeout
+                    ? `flow timeout after ${timeoutS}s`
+                    : (e instanceof Error ? e.message : String(e)),
             };
         }
+        await this._emitTerminal(flow, final, startTime);
+        return final;
+    }
+    // ------------------------------------------------------------------
+    // Notification emission helpers — no-op when no notifier attached.
+    // ------------------------------------------------------------------
+    async _emitStarted(flow) {
+        if (!this._notifier)
+            return;
+        await this._notifier.emit(makeEvent({
+            type: 'flow.started',
+            flowName: flow.name,
+            stepCount: flow.steps.length,
+            metadata: this._eventMetadata,
+        }));
+    }
+    /** Emit `flow.skipped` when `requiredEnv` is unmet. */
+    async _emitSkipped(flow, reason) {
+        if (!this._notifier)
+            return;
+        await this._notifier.emit(makeEvent({
+            type: 'flow.skipped',
+            flowName: flow.name,
+            stepCount: flow.steps.length,
+            error: reason,
+            metadata: this._eventMetadata,
+        }));
+    }
+    async _emitTerminal(flow, result, startTime) {
+        if (!this._notifier)
+            return;
+        let failedStep;
+        for (const r of result.steps) {
+            if (!r.success) {
+                failedStep = { index: r.stepIndex, tool: r.toolName, error: r.error };
+                break;
+            }
+        }
+        await this._notifier.emit(makeEvent({
+            type: result.success ? 'flow.succeeded' : 'flow.failed',
+            flowName: flow.name,
+            durationMs: performance.now() - startTime,
+            success: result.success,
+            error: result.error,
+            failedStep,
+            stepCount: flow.steps.length,
+            executedSteps: result.steps.length,
+            metadata: this._eventMetadata,
+            result,
+        }));
     }
     async _executeSteps(steps, results, previousResult) {
         let lastResult = previousResult;
@@ -147,6 +316,18 @@ export class FlowExecutor {
                 return [false, lastResult];
             }
             const step = steps[i];
+            if (step.type === 'for_each') {
+                // Iterate `step.params.source` and run `step.params.body` once per
+                // element. See _executeForEachStep for the full schema.
+                const [loopOk, loopLast] = await this._executeForEachStep(step, i, lastResult, results);
+                if (!loopOk && !step.optional) {
+                    return [false, lastResult];
+                }
+                if (loopOk) {
+                    lastResult = loopLast;
+                }
+                continue;
+            }
             if (step.type === 'condition' && step.condition) {
                 const result = await this._executeConditionStep(step, i, lastResult, results);
                 if (!result.success) {
@@ -158,9 +339,22 @@ export class FlowExecutor {
                 const result = await this._executeToolStep(step, i, lastResult);
                 results.push(result);
                 if (!result.success) {
+                    if (step.optional) {
+                        // Best-effort step: record the failure but don't abort the flow
+                        // and don't propagate the error as the new lastResult (we'd
+                        // otherwise corrupt downstream variable resolution).
+                        continue;
+                    }
                     return [false, lastResult];
                 }
                 lastResult = result.result;
+                // Capture into flow-scoped vars so later steps can resolve
+                // ${vars.NAME} regardless of how many steps separate them. When
+                // `step.extract` is set, the captured value is the extracted form;
+                // raw stays on `${prev}` / `result.result`.
+                if (step.capture) {
+                    this._vars[step.capture] = step.extract ? result.extracted : result.result;
+                }
             }
             // Small delay between steps
             if (i < steps.length - 1) {
@@ -169,6 +363,69 @@ export class FlowExecutor {
         }
         return [true, lastResult];
     }
+    /**
+     * Execute a `for_each` step: iterate an array source, run a body per item.
+     *
+     * Schema (under step.params):
+     *   source     `${...}` ref or literal array
+     *   body       array of step JSON to run per item
+     *   item_var   capture name for the current item (default 'item')
+     *   index_var  capture name for the index (default 'index')
+     */
+    async _executeForEachStep(step, stepIndex, previousResult, results) {
+        const sourceRaw = resolveValue(step.params['source'], previousResult, this._vars, this._params);
+        const bodyRaw = step.params['body'];
+        const itemVar = step.params['item_var'] || 'item';
+        const indexVar = step.params['index_var'] || 'index';
+        let items = [];
+        if (Array.isArray(sourceRaw)) {
+            items = sourceRaw;
+        }
+        else if (typeof sourceRaw === 'string') {
+            try {
+                const parsed = JSON.parse(sourceRaw);
+                items = Array.isArray(parsed) ? parsed : [];
+            }
+            catch {
+                items = [];
+            }
+        }
+        if (!Array.isArray(bodyRaw) || bodyRaw.length === 0) {
+            results.push({
+                stepIndex,
+                stepId: step.id,
+                toolName: 'for_each',
+                success: true,
+                result: { iterations: 0, items: 0, note: 'for_each body empty/invalid' },
+                durationMs: 0,
+            });
+            return [true, previousResult];
+        }
+        const bodySteps = bodyRaw.map((b) => FlowExecutor.parseStep(b));
+        let last = previousResult;
+        let iterations = 0;
+        for (let idx = 0; idx < items.length; idx++) {
+            if (this._abortFlag)
+                return [false, last];
+            this._vars[itemVar] = items[idx];
+            this._vars[indexVar] = idx;
+            const enabled = bodySteps.filter((s) => s.enabled);
+            const [iterOk, iterLast] = await this._executeSteps(enabled, results, items[idx]);
+            iterations++;
+            if (!iterOk)
+                return [false, iterLast];
+            last = iterLast;
+        }
+        results.push({
+            stepIndex,
+            stepId: step.id,
+            toolName: 'for_each',
+            success: true,
+            result: { iterations, items: items.length },
+            durationMs: 0,
+        });
+        return [true, last];
+    }
     async _executeConditionStep(step, stepIndex, previousResult, results) {
         const startTime = performance.now();
         if (!step.condition) {
@@ -181,7 +438,15 @@ export class FlowExecutor {
                 durationMs: performance.now() - startTime,
             };
         }
-        const conditionResult = evaluateCondition(step.condition, previousResult);
+        // Resolve any ${prev}/${vars}/${params} references in the condition
+        // value before comparing. Without this, condition.value was used
+        // verbatim and any ${vars.X}-style condition silently always took the
+        // wrong branch.
+        const resolvedCondition = {
+            ...step.condition,
+            value: resolveValue(step.condition.value, previousResult, this._vars, this._params),
+        };
+        const conditionResult = evaluateCondition(resolvedCondition, previousResult, results);
         const branchTaken = conditionResult ? 'true' : 'false';
         const conditionStepResult = {
             stepIndex,
@@ -223,55 +488,119 @@ export class FlowExecutor {
     }
     async _executeToolStep(step, stepIndex, previousResult) {
         const startTime = performance.now();
-        let params = resolveVariables(step.params, previousResult);
+        let params = resolveVariables(step.params, previousResult, this._vars, this._params);
         params = applyParameterAliases(step.type, params);
-        params['context_id'] = this._contextId;
-        try {
-            const result = await this._client.execute(step.type, params);
-            const durationMs = performance.now() - startTime;
-            if (step.expected) {
-                const expectationResult = checkExpectation(result, step.expected);
-                if (!expectationResult.passed) {
+        // Only inject context_id for tools that actually accept it. See the
+        // matching gating in the Python executor for the why.
+        const toolDef = this._client.getTool(step.type);
+        if (!toolDef || 'context_id' in toolDef.parameters) {
+            params['context_id'] = this._contextId;
+        }
+        const maxAttempts = Math.max(1, step.retry?.maxAttempts ?? 1);
+        const backoffMs = step.retry?.backoffMs ?? 0;
+        const maxBackoffMs = step.retry?.maxBackoffMs ?? 0;
+        let lastError;
+        let lastExpectation;
+        let lastResult = undefined;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                if (typeof step.timeoutMs === 'number' && step.timeoutMs > 0) {
+                    lastResult = await runWithTimeout(() => this._client.execute(step.type, params), step.timeoutMs);
+                }
+                else {
+                    lastResult = await this._client.execute(step.type, params);
+                }
+                // Apply post-execution extraction (jsonpath or regex capture
+                // groups) BEFORE the expectation check so authors can `expected`
+                // against the extracted value via `field: "<group_name>"`.
+                const extracted = step.extract ? applyExtract(lastResult, step.extract) : undefined;
+                const extractFailed = step.extract !== undefined && extracted === undefined;
+                if (extractFailed) {
+                    lastError = `Extract "${step.extract.mode}" yielded no match for pattern: ${step.extract.pattern}`;
+                    if (attempt + 1 < maxAttempts) {
+                        await sleep(retryDelayMs(attempt, backoffMs, maxBackoffMs));
+                        continue;
+                    }
                     return {
                         stepIndex,
                         stepId: step.id,
                         toolName: step.type,
                         success: false,
-                        result,
-                        error: 'Expectation failed: ' + expectationResult.message,
-                        durationMs,
-                        expectationResult,
+                        result: lastResult,
+                        extracted,
+                        error: lastError,
+                        durationMs: performance.now() - startTime,
+                        attemptsUsed: attempt + 1,
                     };
                 }
+                if (step.expected) {
+                    // Resolve `${prev}/${vars}/${params}` references inside the
+                    // expectation payload before checking. Without this,
+                    // `expected: { equals: "${vars.X}" }` always failed verbatim.
+                    const resolvedExpected = resolveExpectation(step.expected, lastResult, this._vars, this._params);
+                    // Expectation runs against the extracted value when an extract
+                    // block is present (authors typically expect-on the OTP / token
+                    // they just pulled, not the wrapping payload).
+                    const expectationTarget = step.extract ? extracted : lastResult;
+                    lastExpectation = checkExpectation(expectationTarget, resolvedExpected);
+                    if (!lastExpectation.passed) {
+                        lastError = 'Expectation failed: ' + lastExpectation.message;
+                        // Expectation failure is retryable.
+                        if (attempt + 1 < maxAttempts) {
+                            await sleep(retryDelayMs(attempt, backoffMs, maxBackoffMs));
+                            continue;
+                        }
+                        return {
+                            stepIndex,
+                            stepId: step.id,
+                            toolName: step.type,
+                            success: false,
+                            result: lastResult,
+                            extracted,
+                            error: lastError,
+                            durationMs: performance.now() - startTime,
+                            expectationResult: lastExpectation,
+                            attemptsUsed: attempt + 1,
+                        };
+                    }
+                }
                 return {
                     stepIndex,
                     stepId: step.id,
                     toolName: step.type,
                     success: true,
-                    result,
-                    durationMs,
-                    expectationResult,
+                    result: lastResult,
+                    extracted,
+                    durationMs: performance.now() - startTime,
+                    expectationResult: lastExpectation,
+                    attemptsUsed: attempt + 1,
                 };
             }
-            return {
-                stepIndex,
-                stepId: step.id,
-                toolName: step.type,
-                success: true,
-                result,
-                durationMs,
-            };
-        }
-        catch (e) {
-            return {
-                stepIndex,
-                stepId: step.id,
-                toolName: step.type,
-                success: false,
-                error: e instanceof Error ? e.message : String(e),
-                durationMs: performance.now() - startTime,
-            };
+            catch (e) {
+                if (e instanceof TimeoutAbort) {
+                    lastError =
+                        `Step timed out after ${step.timeoutMs}ms` +
+                            ` (attempt ${attempt + 1}/${maxAttempts})`;
+                }
+                else {
+                    lastError = e instanceof Error ? e.message : String(e);
+                }
+            }
+            if (attempt + 1 < maxAttempts) {
+                await sleep(retryDelayMs(attempt, backoffMs, maxBackoffMs));
+            }
         }
+        return {
+            stepIndex,
+            stepId: step.id,
+            toolName: step.type,
+            success: false,
+            result: lastResult,
+            error: lastError ?? 'step failed',
+            durationMs: performance.now() - startTime,
+            expectationResult: lastExpectation,
+            attemptsUsed: maxAttempts,
+        };
     }
     /**
      * Load a flow from a JSON file.
@@ -287,10 +616,25 @@ export class FlowExecutor {
     static parseFlow(data) {
         const stepsData = (data['steps'] ?? []);
         const steps = stepsData.map(s => FlowExecutor.parseStep(s));
+        const timeoutSecondsRaw = data['timeoutSeconds'] ?? data['timeout_seconds'];
+        const timeoutSeconds = typeof timeoutSecondsRaw === 'number' && Number.isFinite(timeoutSecondsRaw)
+            ? timeoutSecondsRaw
+            : undefined;
+        const requiredEnvRaw = data['requiredEnv'] ?? data['required_env'];
+        const requiredEnv = Array.isArray(requiredEnvRaw)
+            ? requiredEnvRaw
+            : undefined;
+        const parametersRaw = data['parameters'] ?? data['params'];
+        const parameters = parametersRaw && typeof parametersRaw === 'object' && !Array.isArray(parametersRaw)
+            ? parametersRaw
+            : undefined;
         return {
             name: String(data['name'] ?? 'Unnamed Flow'),
             description: data['description'],
             steps,
+            timeoutSeconds,
+            requiredEnv,
+            parameters,
         };
     }
     /**
@@ -299,11 +643,18 @@ export class FlowExecutor {
     static parseStep(data) {
         const stepId = String(data['id'] ?? generateStepId());
         const stepType = String(data['type'] ?? '');
-        // Extract params (everything except metadata)
+        // Extract params (everything except metadata). Reserved step-level keys
+        // get stripped so they aren't sent to the http-server's strict
+        // tools_validate as unknown tool params.
         const params = {};
         const keysToRemove = new Set([
             'type', 'selected', 'enabled', 'expected',
             'condition', 'onTrue', 'onFalse', 'on_true', 'on_false', 'id',
+            // Lap-1.5 step-level extensions:
+            'retry', 'timeout', 'timeoutMs', 'timeout_ms',
+            'optional', 'tags', 'note',
+            // Lap-2 step-level extensions:
+            'capture', 'extract',
         ]);
         // Only remove 'description' if this tool doesn't use it as a parameter
         if (!TOOLS_WITH_DESCRIPTION_PARAM.has(stepType)) {
@@ -327,6 +678,7 @@ export class FlowExecutor {
                 notEmpty: (expData['notEmpty'] ?? expData['not_empty']),
                 field: expData['field'],
                 matches: expData['matches'],
+                oneOf: (expData['oneOf'] ?? expData['one_of']),
             };
         }
         // Parse condition
@@ -353,6 +705,21 @@ export class FlowExecutor {
             onFalse = onFalseData.map(s => FlowExecutor.parseStep(s));
         }
         const enabled = (data['enabled'] ?? data['selected'] ?? true);
+        // Step-level extensions: retry / timeout / optional / tags.
+        let retry;
+        if (data['retry'] && typeof data['retry'] === 'object') {
+            const r = data['retry'];
+            const maxAttempts = Number(r['maxAttempts'] ?? r['max_attempts'] ?? 1);
+            retry = {
+                maxAttempts: Number.isFinite(maxAttempts) ? maxAttempts : 1,
+                backoffMs: Number(r['backoffMs'] ?? r['backoff_ms'] ?? 200),
+                maxBackoffMs: Number(r['maxBackoffMs'] ?? r['max_backoff_ms'] ?? 5000),
+            };
+        }
+        const timeoutMsRaw = data['timeoutMs'] ?? data['timeout_ms'];
+        const timeoutMs = typeof timeoutMsRaw === 'number' && Number.isFinite(timeoutMsRaw)
+            ? timeoutMsRaw
+            : undefined;
         return {
             id: stepId,
             type: stepType,
@@ -363,7 +730,30 @@ export class FlowExecutor {
             condition,
             onTrue,
             onFalse,
+            timeoutMs,
+            retry,
+            optional: Boolean(data['optional']),
+            tags: Array.isArray(data['tags']) ? data['tags'] : undefined,
+            capture: typeof data['capture'] === 'string' ? data['capture'] : undefined,
+            extract: parseExtract(data['extract']),
         };
     }
 }
+function parseExtract(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const mode = r['mode'];
+    if (mode !== 'jsonpath' && mode !== 'regex')
+        return undefined;
+    const pattern = typeof r['pattern'] === 'string' ? r['pattern'] : '';
+    if (!pattern)
+        return undefined;
+    return {
+        mode,
+        pattern,
+        on: typeof r['on'] === 'string' ? r['on'] : undefined,
+        flags: typeof r['flags'] === 'string' ? r['flags'] : undefined,
+    };
+}
 //# sourceMappingURL=executor.js.map