Skip to content

feat(workflow): add optional precheck gate to skip empty runs - #2303

Open
Bartok9 wants to merge 1 commit into
block:mainfrom
Bartok9:bartok9/workflow-precheck-gate
Open

feat(workflow): add optional precheck gate to skip empty runs#2303
Bartok9 wants to merge 1 commit into
block:mainfrom
Bartok9:bartok9/workflow-precheck-gate

Conversation

@Bartok9

@Bartok9 Bartok9 commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Refs #2297

Problem

Schedule-triggered workflows fire on a cron/interval. Today the only convergence control is per-step if: conditions. A poller workflow ("every 15m, check X, and if there's new work have an agent summarize it") still spins up the step chain — and any agent/webhook/message action — on every tick even when there's nothing to do. On a busy relay with many scheduled agent workflows that's a real, silent cost and a source of empty-run channel noise.

Why it matters

Buzz makes agents first-class; scheduled agent workflows are a natural pattern. A cheap gate that decides whether there's work before doing expensive work makes them affordable and quiet. This is the same zero-cost-gate idea we contributed to the OpenClaw (job.precheck) and Hermes (NO_WORK wake gate) cron systems.

What this adds

A workflow-level precheck evalexpr gate, evaluated once at run start, before any step:

name: pr-triage
trigger:
  on: schedule
  cron: "*/15 * * * *"
precheck: "trigger_open_pr_count > 0"   # same vars as step if:
steps:
  - id: summarize
    action: { send_message: { text: "…" } }
  • precheck false → run short-circuits with zero step actions, returns Completed with a skipped-precheck trace entry.
  • Absent precheck → unchanged behavior (serde default None).

Design / safety

  • Additive. Existing workflows are byte-for-byte unaffected.
  • Reuses evaluate_condition — inherits the same 4 KB expression cap + 100 ms timeout envelope as step if:. No new execution surface, no shell.
  • Fail-open. A precheck that errors runs the steps (a bad gate never silently disables a workflow) and logs a warning — surfaced in the trace.
  • Stateless in v1 (trigger context only), matching step if:.

How to test

cargo test -p buzz-workflow precheck   # parse + JSON round-trip + default-None
cargo clippy -p buzz-workflow          # clean
cargo fmt -p buzz-workflow --check

The gate's decision uses the same evaluate_condition primitive that's already covered by the executor condition tests (condition_*).

Notes / open to maintainer direction

Signed-off-by DCO.

@Bartok9
Bartok9 requested a review from a team as a code owner July 21, 2026 22:25
@Bartok9
Bartok9 force-pushed the bartok9/workflow-precheck-gate branch 3 times, most recently from 8e6a86b to 88d11e0 Compare July 25, 2026 18:19
Adds a workflow-level `precheck` evalexpr gate evaluated once at run start,
before any step executes. When it evaluates to false the run short-circuits
with zero step actions (no messages, webhooks, or agent turns) and returns a
completed result with a skipped-precheck trace entry.

This lets a scheduled poller workflow ("every 15m, if there's new work, have
an agent summarize it") cheaply skip empty ticks instead of spinning up the
step chain each time — the same zero-cost-gate pattern we contributed to the
OpenClaw and Hermes cron systems.

- Additive: workflows without `precheck` are unchanged (serde default None).
- Reuses the existing `evaluate_condition` machinery (4 KB expr cap + 100 ms
  timeout), so no new execution surface and no shell — same safety envelope
  as step `if:` conditions.
- Fail-open: a precheck that errors runs the steps (a bad gate never silently
  disables a workflow) and logs a warning.
- Tests: precheck field parse + JSON round-trip + default-None.

Refs block#2297

Signed-off-by: Bartok9 <danielrpike9@gmail.com>
@Bartok9
Bartok9 force-pushed the bartok9/workflow-precheck-gate branch from 88d11e0 to 188c593 Compare July 28, 2026 13:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant