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

1. Compile

   The workflow compiler reads the YAML, expands macros, substitutes parameters, and groups consecutive action steps into batched server calls.

2. 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.

3. 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"

4. Execute

   Batches are executed sequentially against the BAP server. Cache hits skip DOM traversal entirely.

Usage

# Execute with fusion optimization
bap run checkout-flow

# Pass parameters
bap run checkout-flow --param email=[e-mail] --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"="[e-mail]"
                      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:

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

bap run checkout-flow --dry-run
# Output includes: Cache: 12/15 entries warm (80%)

Forcing a warm-up

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:

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: "[e-mail]"
      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

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.