Automation tasks: support holiday-aware scheduling via an optional pre-delivery condition (skip) hook

[cyhano]

Summary

weekly and cron rules follow the civil calendar only. In regions with statutory-holiday makeup workdays (e.g. China: holidays fall on Mon–Fri, and some Saturdays/Sundays become workdays), "run on workdays" cannot be expressed by any weekday set or cron field — weekdays: [1,2,3,4,5] and 0 9 * * 1-5 are both wrong under holiday shifts. Please add an optional, generic pre-delivery condition hook so a rule can skip individual occurrences at the scheduler level.

The real-world semantics we need

"Workday" here = civil weekday ∪ makeup weekend workday − statutory holiday. This data is publicly available (e.g. the holiday-cn dataset) and easy to evaluate with a one-line script. The scheduler itself doesn't need to know any holiday calendar — it only needs a way to ask a condition before delivering.

Current workaround (in production, and its costs)

The only way today is to trigger every day and gate inside the prompt:

cron 36 9 * * * (Asia/Shanghai)
prompt step 1: bash ~/.agents/skills/workday/scripts/workday.sh
  exit 0 (workday) → proceed with the real task
  exit 1 (offday)  → end immediately, do nothing
  exit 2 (error)   → fallback per prompt convention

Pain points:

1. Every off-day still wakes a session: a full agent turn is spun up just to say "not a workday, bye" — wasted tokens and a pointless transcript, daily.
2. No hard gate: skipping relies on the model obeying the prompt; there is no scheduler-level guarantee.
3. Distorted metadata: the task list shows "Every day" while the real cadence is "workdays only"; delivery records fill with non-deliveries.
4. Error policy is prose, not config: what happens when the holiday data source fails is whatever the model decides that morning.

Proposal

A. Generic pre-delivery condition hook (recommended, fully general):
Add an optional field to recurring rules (daily/weekly/cron), e.g.:

{
  "cron": { "expression": "36 9 * * *", "time_zone": "Asia/Shanghai" },
  "condition": { "command": "bash ~/.agents/skills/workday/scripts/workday.sh", "on_error": "skip" }
}

• Runs the command in the session workspace just before delivery; exit 0 → deliver, non-zero → skip that occurrence.
• A skipped occurrence records a lightweight skipped entry in delivery history (so the gap is explainable) and does not wake the session.
• on_error: "skip" | "deliver" — explicit, configured failure policy instead of model judgment.
• Needs a timeout and runs under the same permission preset as the session; no new trust surface beyond what the prompt could already do — it just moves the gate to the right layer.

B. Documentation-only fallback (tiny, still valuable):
State in the schedule_create tool description that wall-clock rules follow the civil calendar only and cannot express regional holiday calendars; for "workdays only" semantics, trigger daily and gate inside the prompt (with the pattern above).

C. Rendering nicety: when delivery history contains skipped-by-condition entries, show the rule's effective cadence as "workdays (condition-gated)" rather than "Every day".

Why not a built-in "china workday" option

Holiday calendars are regional, versioned yearly by government decree, and would hard-code policy into the harness. A condition hook lets users (or their skill scripts) own the calendar while the scheduler owns the mechanics — same split this repo already uses elsewhere.

Environment

• @deepseek-ai/dsh 0.2.0-rc.2 (macOS, Web GUI)
• Verified from installed sources: ScheduleCreateRequest selectors (after_seconds/at/every_seconds/daily/weekly/cron) have no condition/skip concept; delivery history exists and could carry skipped entries.

Happy to test a preview build. Thanks!

[argszero]

Your option A is the right seam, and the tree agrees with your diagnosis of where it is missing: there is no waterfall anywhere on the delivery path. Delivery is a straight line — packages/schedule/schedule/src/runtime.ts:85-142 — filter due tasks, resolveAgent (:101), build the reminder as a UserMessage with source.kind === 'schedule' (:119-122), agent.followup(message) (:123), sessions.flush (:124), then commit the advance and the delivery record. The package's whole event surface is schedule/change and schedule/changed (packages/schedule/schedule/src/types.ts:365 and :478), neither of which is a decision point. So a per-rule condition cannot be a plugin today; it is a core change, exactly as you propose it.

What is reachable today, from a plugin and without touching core, is the first pain on your list — the wasted model turn. Delivery ends in an inbox message, and every step of every session funnels through one waterfall, so a plugin can gate the occurrence right before the model would see it:

• agent/pre-step is handed payload.messages = the messages claimed from the inbox for this step (packages/core/agent-loop/src/agent.ts:275, claim at :272), and its contract is "Reject a proposed step or replace the messages that enter it. Calling next() preserves the current messages" (packages/core/agent/src/runtime-types.ts:307-320), with the result type at :112-119.
• A UserMessage always carries its source (packages/llm/llm/src/message.ts:139-148), so messages.some(m => m.source.kind === 'schedule') identifies the reminder — no text matching needed.
• Returning { kind: 'reject' } ends the turn as blocked and spends no model call (agent-loop/src/agent.ts:317-320). An { kind: 'enter', messages: [] } at step 0 does the same and ends completed instead (:321-327: "still owns the initial turn boundary, but it spends no model call"). Either way the occurrence costs one session restore plus one inbox claim, and per the inbox contract the claimed message "ends here: it is neither discarded nor re-emitted as a user/message" — so no transcript line and no request.

Scoped honestly, that is "no model turn", not "no wake": resolveAgent has already restored the session before the message exists, so the scheduler still wakes it, and your pains 3 and 4 are untouched — the delivery record is still written (the commit at :127-142 runs regardless of what the step does), the task list still says "Every day", and the failure policy is still your plugin's config rather than a rule field. Your option 2 (one line in schedule_create's description: wall-clock rules follow the civil calendar only) stays worth doing on its own.

Two constraints that decide whether this is the right shape for you:

1. Scope. The listener sees the session id (payload.agent.session.header.id) and the rendered reminder text, not the schedule record id — so a per-rule condition is not expressible from this seam. A per-session or global condition is, and your workday gate is global, so it fits. If you later want "rule 3 is holiday-aware, rule 4 is not", that is option A again.
2. Trust surface — the part I would not hand-wave. Your proposal runs the condition "under the same permission preset as the session". A plugin-side gate has to arrange that itself: either the condition goes through the shell service the way the session's own bash tool does, with the session's sandbox preset, or the plugin evaluates a policy with no command at all (a holiday dataset it reads itself). The second has no new trust surface; the first is a real integration question, and it is one more reason the core proposal is better than the plugin workaround, since core can inherit the preset mechanically instead of re-deriving it.

I maintain published harness plugins, so if it is useful I am happy to ship this gate as one (@argszero/dsh-schedule-condition-gate, npm) with the condition as config — that would give you a working skip today — but it would be a workaround for the missing delivery seam rather than the seam itself, and I would rather state that plainly than sell it as the fix.