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 5 times, most recently from 188c593 to 18924a7 Compare July 29, 2026 13:18
@cameronhotchkies cameronhotchkies added the triage-ready Appropriate for agentic review label Jul 30, 2026
@Bartok9
Bartok9 force-pushed the bartok9/workflow-precheck-gate branch 7 times, most recently from 46debf0 to 4a379a6 Compare August 5, 2026 13:19
@Bartok9
Bartok9 force-pushed the bartok9/workflow-precheck-gate branch 3 times, most recently from e0d77f5 to a5c19b3 Compare August 14, 2026 13:27
@Bartok9
Bartok9 force-pushed the bartok9/workflow-precheck-gate branch 2 times, most recently from d495c95 to 0bd0d7b Compare August 19, 2026 13:22
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>
(cherry picked from commit d495c95)
Signed-off-by: Bartok9 <259807879+Bartok9@users.noreply.github.com>
@Bartok9
Bartok9 force-pushed the bartok9/workflow-precheck-gate branch from 0bd0d7b to a53cee2 Compare August 19, 2026 16:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage-ready Appropriate for agentic review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants