Goals
Define the outcomes the system is trying to achieve.
OPEN SOURCE · BETA 0.3.0-beta.2
GRAIL
A different approach to automation
Define outcomes, not workflows.
GRAIL is an open-source runtime for bounded autonomy. Describe the outcome you want, the conditions required for success, and the capabilities available to achieve it. GRAIL determines which actions to execute without requiring a predefined sequence.
01 / APPROACH
How GRAIL works
Traditional workflows prescribe a sequence of actions, including the decisions and branches that determine what happens next. Changes to the process often require changes to the workflow itself.
GRAIL takes a different approach. You define the conditions required for success and the capabilities available to satisfy those conditions. GRAIL evaluates the current environment and selects actions that move it toward the desired outcome.
Define the environment, not the path.
For example, consider onboarding a new customer. Successful onboarding requires a customer profile, verified contact information, and acceptance of the required terms.
GRAIL examines which conditions have already been satisfied and identifies capabilities that can resolve the remaining ones. As conditions change, additional actions become available. If multiple capabilities can satisfy the same condition, GRAIL can select among them.
The result is an execution sequence that emerges from the current state of the environment and the capabilities available within it.
In v0.3.0-beta.2, GRAIL detects cyclic dependency paths and backtracks to alternative affordances when available. If no viable path remains, the pursuit terminates as unresolvable instead of continuing indefinitely. The release also supports literal string values in affordance inputs alongside references to configured inputs and capability outputs. Read about cyclic dependency resolution ↗.
The environment defines what is possible. GRAIL determines what to do next.
02 / ARCHITECTURE
The GRAIL model
GRAIL uses a small set of elements to describe an environment in which autonomous action can take place.
Conditions
Represent facts about the environment that can be satisfied or unsatisfied.
Affordances
Describe possible actions, including their preconditions and effects.
Capabilities
Perform the actual work, such as calling an API or running a script.
An environment of possibilities
Illustrative relationships, not a prescribed execution order.
Two affordances can establish Condition A. The runtime can select an available producer based on the current state.
Together, these elements form a network of possibilities. An affordance becomes available when its required conditions are satisfied. Successful execution establishes new conditions, which may make additional affordances available.
GRAIL navigates this network by identifying unmet conditions and selecting affordances capable of satisfying them. The process continues until the goal is achieved or no available capability can resolve the remaining conditions.
Autonomy emerges from the composition of the environment.
03 / BENEFITS
Why GRAIL?
GRAIL offers a different way to design and operate automated systems. Its architecture provides several useful properties.
Bounded autonomy
Autonomous action within an explicitly defined environment. Designers establish boundaries while the runtime selects actions.
Adaptable by design
New capabilities introduce additional ways to satisfy existing conditions without rewriting a predefined workflow.
Reusable capabilities
Independent APIs, scripts, and application functions participate through replaceable bindings.
Predictable mechanics
Consistent rules for evaluating conditions and applying effects, with flexibility in how actions are selected.
No LLM required
Goal pursuit works without a language model. LLM-based selection or capabilities can be introduced where useful.
Human participation
Interactive terminal capabilities can request input from a person without introducing a special workflow step.
Observable execution
CLI progress reporting, structured API events, execution timing, and observations help explain what happened during a pursuit.
Optional recovery
When a pursuit cannot reach its goal, GRAIL can coordinate best-effort compensating actions in reverse execution order. Capabilities define how to recover; GRAIL manages when and in what order recovery is attempted.
04 / RESEARCH
Research & Evidence
GRAIL explores bounded autonomy through environmental composition. A published research study examines the approach across six experiment families and eleven recorded scenarios, including alternative actions, nested pursuits, failure behavior, and architectural limits.
The paper, experimental evidence, configurations, and reproducibility documentation are available for inspection and further exploration.
05 / GET STARTED
Get started with GRAIL
GRAIL is an open-source runtime available through npm. Install it locally and begin experimenting with goal-directed automation using your own capabilities.
1. Install GRAIL
Requires Node.js and npm. Both the npm latest and beta tags currently install v0.3.0-beta.2.
npm install -g @mamund/grail2. Create and run a world
Use grail init my-world, then cd my-world, grail validate, and grail run --output=summary --progress to see goal pursuit and live progress.
For a guided walkthrough, follow the command-line tour ↗.
3. Compose or embed GRAIL
Define a goal, identify the conditions required for success, and connect capabilities through Node, HTTP, or stdio bindings. Interactive stdio capabilities can involve a person when needed.
Use the CLI for standalone pursuits or embed GRAIL through its JavaScript API. The API consumer example ↗ demonstrates progress events and timing.
4. Explore optional recovery
Use grail run --recover to enable best-effort compensation when a pursuit becomes unresolvable. Recovery handlers belong to capabilities, and compensation does not change the original pursuit outcome. See the recovery specification ↗, capability recovery guide ↗, and portable recovery demo ↗.
Ready to explore GRAIL?
06 / PROJECT
About GRAIL
GRAIL is an open-source project exploring how autonomous systems can be designed through the composition of goals, conditions, and capabilities.
The project offers a lightweight runtime, working examples, and an architecture for building goal-directed automation without prescribing execution sequences.
GRAIL v0.3.0-beta.2 is available as a public beta. Developers, researchers, and automation practitioners are invited to explore the project, experiment with the runtime, and contribute to its development.
Explore GRAIL on GitHub ↗