Flow Executor & Validation
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Flow Executor and Validation system serves as the runtime engine for SweepBot's natural language automation. It is responsible for taking interpreted Flow Definitions (Abstract Syntax Trees) and executing them recursively while enforcing strict safety guardrails. This system ensures that user-defined automations, such as daily bonus collections or spinning strategies, operate within the "Responsible Play" framework defined by the project.
The architecture is built around a recursive execution model that tracks metrics in real-time, including action counts, wagered amounts, and net results. Validation occurs both during the interpretation phase and immediately prior to execution to prevent automations that might lead to excessive loss or extended play durations.
Sources: packages/flows/README.md:3-33, packages/flows/src/executor/executor.ts, packages/flows/src/interpreter/interpreter.ts:36-41
Flow Execution Engine
The FlowExecutor class is the central component responsible for traversing the Flow AST. It processes different node types—such as actions, conditions, loops, and sequences—returning a comprehensive FlowExecutionResult that includes detailed metrics and execution logs.
Execution Workflow
Execution follows a recursive pattern where the root node (often a sequence or action) is passed to the executor. The engine maintains an internal context and tracks performance metrics throughout the lifecycle of the flow.
The diagram above illustrates the recursive traversal and metric tracking logic utilized during flow execution.
Sources: packages/flows/src/executor/executor.ts, packages/flows/README.md:162-171, packages/flows/src/tests/integration.test.ts:98-106
Execution Result Metrics
Every execution generates a set of metrics to provide transparency into the automation's performance and safety compliance.
| Metric | Description |
|---|---|
totalDuration | Total time elapsed during the flow execution in milliseconds. |
actionsExecuted | Count of successful FlowActionNode executions. |
totalWagered | Cumulative amount of currency wagered during the session. |
totalWon | Cumulative winnings across all actions. |
netResult | The final profit or loss (Won - Wagered). |
loopIterations | Number of times a FlowLoopNode successfully cycled. |
Sources: packages/flows/README.md:78-91, packages/flows/src/executor/executor.ts
Responsible Play Validation
Validation is a non-negotiable phase of the pipeline. The ResponsiblePlayValidator ensures that every flow adheres to mandatory safety caps, regardless of user input.
Mandatory Guardrails
Guardrails are categorized by their source: user_specified, system_default, or system_mandatory. Mandatory guardrails cannot be overridden by users and are enforced to prevent addictive patterns.
Validation logic ensures that safety constraints like maximum session time are applied before the scheduler or executor activates the flow.
Sources: packages/flows/src/validator/responsible-play-validator.ts, packages/flows/README.md:173-186, packages/flows/src/interpreter/interpreter.ts:40-45
Core Guardrail Types
| Guardrail Type | Default Behavior | Overridable |
|---|---|---|
max_duration | Caps session at 2 hours (system default). | Yes (by user) |
cool_down_check | Blocks execution if user is in a cool-down period. | No |
max_iterations | Limits loops to 100 iterations per node. | No |
max_loss | Stops execution if net result falls below threshold. | Yes |
Sources: packages/flows/README.md:176-186, packages/flows/src/validator/responsible-play-validator.ts
Node Execution Logic
The system utilizes a discriminated union for FlowNode, allowing the executor to handle diverse logic structures within the AST.
Action Nodes (FlowActionNode)
Action nodes represent the actual interactions with casino platforms.
- Actions:
open_platform,login,claim_bonus,open_game,spin,close_platform. - Failure Strategies: Nodes include an
onFailureproperty (e.g.,stop,skip,retry) to determine behavior when an action fails.
Loop Nodes (FlowLoopNode)
Loops wrap actions or sequences with safety constraints.
- Constraints: Every loop node is assigned a
maxIterations(default 100) andmaxDuration(default 30 minutes) to prevent infinite execution.
Condition Nodes (FlowConditionNode)
Conditions enable branching logic based on variables like PROFIT, BALANCE, or BONUS.
- Operators: Support for
>,<,>=,<=,==,!=,contains, andexists.
Sources: packages/flows/src/types.ts, packages/flows/src/interpreter/interpreter.ts:140-192, packages/flows/README.md:213-225
Flow Lifecycle Integration
The validation and execution systems are integrated into a larger lifecycle that includes interpretation and scheduling.
The sequence above details how validation is interleaved between interpretation and final execution.
Sources: packages/flows/src/tests/integration.test.ts:25-54, packages/flows/README.md:60-112
Summary
The Flow Executor & Validation module provides a robust, safe environment for sweepstakes automation. By combining a recursive AST execution engine with a mandatory validation layer, the system balances user flexibility with responsible play standards. The use of detailed metric tracking and fail-safe node configurations ensures that every automation is transparent, auditable, and safe for the user ecosystem.