[Proposal] Scheduled-workflow precheck gate: skip runs with zero token/action cost

[Bartok9]

Summary

Add an optional precheck gate to Schedule-triggered workflows so a recurring workflow can cheaply decide whether there is work before executing its steps (which may call agents, webhooks, or post messages). When the gate says "no work," the run is recorded as skipped and no actions fire — no agent turn, no webhook, no channel noise.

This mirrors a pattern we recently upstreamed to two other agent runtimes and would make Buzz's scheduled agent workflows materially cheaper and quieter.

Problem

TriggerDef::Schedule fires a workflow on a cron/interval. Today the only convergence control is per-step if: (evalexpr) conditions evaluated against trigger context + prior step outputs. For a poller workflow ("every 15m, check X, and if there's something new, have an agent summarize it"), each tick still spins up the step chain (and any agent/webhook action) even when there is nothing to do. On a busy relay with many scheduled agent workflows, that is a large, silent cost and a source of empty-run channel noise.

Prior art (why we think this is the right shape)

We contributed the same idea to OpenClaw (job.precheck) and Hermes (NO_WORK wake gate) cron systems: a cheap gate runs before the expensive work; exit 0 / WORK_NEEDED → run, exit 2 / NO_WORK → skip. The key lessons we'd carry over:

• The gate lives inside the scheduler run path (not a sidecar) so there's one source of truth and no double-firing.
• One documented contract (exit code + a NO_WORK stdout convention) with tests.
• Skipped runs are recorded distinctly (not errors) for observability.

Proposed shape (seeking maintainer direction before implementing)

A workflow-level, evalexpr-based gate that reuses the existing evaluate_condition machinery (no new execution surface, no shell):

name: pr-triage
trigger:
  on: schedule
  cron: "*/15 * * * *"
precheck: "trigger_open_pr_count > 0"   # evalexpr, same vars as step if:
steps:
  - action: { send_message: { text: "…" } }

• If precheck evaluates false → the run is skipped (distinct status, metric), zero actions.
• Purely additive: workflows without precheck behave exactly as today.
• Reuses evaluate_condition (already bounded: 4 KB expr cap + 100 ms timeout), so it inherits the same safety envelope — no shell/command execution added to the relay.

Deliberately out of scope

• Arbitrary shell/command prechecks (security surface in the relay — not proposing that).
• Any change to non-schedule triggers.

Open questions for maintainers

1. Is a workflow-level precheck (vs. telling authors to gate step 1 with if:) worth the ergonomics + the distinct skipped-run status/metric?
2. Preferred skipped-run surfacing: a workflow-run status value, a metric only, or both?
3. Would you want the gate to have access to any state beyond current trigger context (e.g., last-run state) — or keep it stateless in v1?

Happy to implement behind a small, additive PR with tests + docs once the shape is agreed. I recently shipped #2289 (agent error_class) and #2296 (offline-mention notice) in this area and can follow the same minimal-diff approach.

[Bartok9]

Went ahead and implemented Way A (workflow-level precheck) since it's fully additive and low-risk — happy to adjust to maintainer preference.

The two ways I weighed:

• A — workflow-level precheck: <evalexpr> (chosen): one gate evaluated once at run start, before any step. Clean single knob; distinct skipped trace. Reuses evaluate_condition (4 KB/100 ms caps) — no new surface, no shell.
• B — tell authors to gate step 1 with if:: no new field, but doesn't short-circuit the run (the run still starts, later steps that reference step-1 output get awkward), and there's no single "skip the whole poll" signal or metric.

A is the better ergonomic + gives a clean skip semantics, so I built that. Open to folding it into a Schedule-only field if you'd rather it not apply to event-triggered workflows.

Answers to my own 3 questions, as implemented (tell me to change any):

1. Workflow-level gate (vs step if:) — yes, for the single-skip semantics above.
2. Skipped surfacing — trace entry {"precheck","status":"skipped","reason":"precheck-false"}; run still finalizes Completed. Can add a dedicated status/metric if you want it distinct from completed.
3. State — v1 is stateless (trigger context only), matching step if:. Left last-run state out deliberately.

PR up: additive, fail-open on eval error, tests included.