> ## Documentation Index
> Fetch the complete documentation index at: https://piyushvyas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Fusion

> Compiler-optimized workflow execution with batching, dry-run, and cache warming

`bap run` is the optimized path for executing workflows. It compiles workflow YAML into an execution plan that batches consecutive actions, applies fusion flags, and leverages the action cache for instant replay.

## How It Works

<Steps>
  <Step title="Compile">
    The workflow compiler reads the YAML, expands macros, substitutes parameters, and groups consecutive action steps into batched server calls.
  </Step>

  <Step title="Batch">
    Consecutive batchable actions (click, fill, type, press, select, check, uncheck, hover, scroll)
    are merged into a single `fused-act` server call. Non-batchable steps (goto, observe, extract,
    screenshot, wait) create batch boundaries.
  </Step>

  <Step title="Fuse">
    The compiler sets fusion flags on batches: - First action batch after a navigate gets `preObserve:
          true` - Last action batch before a navigate/extract gets `postObserve: true` - Intermediate
    observe batches get `responseTier: "minimal"`
  </Step>

  <Step title="Execute">
    Batches are executed sequentially against the BAP server. Cache hits skip DOM traversal entirely.
  </Step>
</Steps>

## Usage

```bash theme={null}
# Execute with fusion optimization
bap run checkout-flow

# Pass parameters
bap run checkout-flow --param email=user@test.com --param product="Widget"

# Dry run: show the execution plan without running
bap run checkout-flow --dry-run

# Force cache warming before execution
bap run checkout-flow --warm
```

## Execution Plan

The compiler produces an `ExecutionPlan` with batched steps:

```
Original: 8 steps
Compiled: 4 batches (50% reduction)

Batch 1: navigate  → goto https://store.example.com
Batch 2: fused-act → fill:label:"Email"="user@test.com"
                      fill:label:"Password"="secret"
                      click:role:button:"Sign in"
          fusion: { preObserve: true, postObserve: true }
Batch 3: navigate  → goto https://store.example.com/cart
Batch 4: fused-act → click:role:button:"Place Order"
          fusion: { preObserve: true, postObserve: true }
```

### Batch Types

| Type          | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| `fused-act`   | Multiple action steps executed as a single `agent/act` call |
| `navigate`    | A `goto` step                                               |
| `observe`     | An `observe` step                                           |
| `extract`     | An `extract` step                                           |
| `screenshot`  | A `screenshot` step                                         |
| `wait`        | A `wait` step                                               |
| `conditional` | A step with `repeat: { until: ... }`                        |

## Dry Run

Preview what the compiler produces without executing anything:

```bash theme={null}
bap run checkout-flow --dry-run
```

This outputs:

* The number of original steps vs compiled batches
* Each batch with its type, steps, and fusion flags
* The estimated call reduction percentage
* Cache warmth status (how many selectors are already cached)

## Cache Warming

After a successful workflow run, BAP saves a cache manifest at `~/.bap/cache/workflows/<name>.json`. The manifest tracks:

* **Workflow hash** -- SHA256 of the YAML content (invalidates on change)
* **Cache keys** -- Action cache entries used during the run
* **Selector map** -- Resolved selector mappings for fast replay
* **Batch timings** -- Duration per batch for performance tracking

### Checking cache warmth

```bash theme={null}
bap run checkout-flow --dry-run
# Output includes: Cache: 12/15 entries warm (80%)
```

### Forcing a warm-up

```bash theme={null}
bap run checkout-flow --warm
```

This executes the workflow once to populate the action cache, then the next `bap run` will hit cached selectors and skip DOM traversal.

## Compiler Details

### Macro Expansion

Macros are expanded before batching. The compiler supports up to 10 expansion passes for nested macros and detects circular references:

```yaml theme={null}
macros:
  login:
    params:
      user: ""
      pass: ""
    steps:
      - type: fill
        args: label:"Email"="{{user}}"
      - type: fill
        args: label:"Password"="{{pass}}"
      - type: act
        args: click:role:button:"Sign in"

steps:
  - type: macro
    macro: login
    macroParams:
      user: "admin@test.com"
      pass: "secret"
```

The three macro steps are inlined and batched into a single `fused-act` call.

### Repeat Expansion

Numeric `repeat: N` is expanded at compile time by duplicating the step N times. Conditional `repeat: { until: ... }` is preserved as a `conditional` batch for runtime evaluation.

### Parameter Substitution

All `{{param}}` placeholders in step `args` and `label` fields are substituted with merged params (workflow defaults + runtime overrides) before batching.

## Workflow vs Run

| Command                   | What it does                                          |
| ------------------------- | ----------------------------------------------------- |
| `bap workflow run <name>` | Sequential execution, no compilation, no batching     |
| `bap run <name>`          | Compiled execution with batching, fusion, and caching |

<Tip>
  Use `bap workflow run` for debugging and `bap run` for production. The workflow runner executes
  steps one at a time, making it easier to identify which step failed. The optimized runner batches
  steps, which is faster but harder to debug.
</Tip>