ChatGPTClaudeGrok / X / CursorGemini

DSH plugin schedule: repeat rules, time zones, catch-up

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessScheduleRepeat rulesTime zones
DSH plugin schedule: seven authoritative timing types, canonical UTC scheduledAt, cron versus RRULE, delivery targets, and catch-up semantics.

Scheduled tasks fail in two places: local time treated as absolute time, and "missed once" read as "replay every slot." DSH plugin's schedule removes ambiguity with seven authoritative timing types plus one canonical UTC instant, and its catch-up policy explicitly coalesces rather than replays.

Seven timing types are all authoritative

Normalization preserves the committed occurrence instant and never converts a type.(source)

Schedule stores host tasks independently of Session activation. One management API operates by id, and one evaluator handles all seven authoritative timing types:

TypeInput
afterA positive afterSeconds plus a one-shot UTC target
atA one-shot UTC target, accepting an explicit offset or local datetime with zone
everyAn integer everySeconds of at least 60, aligned to the committed anchor
dailyA local time as HH:mm:ss.SSS plus an explicit timeZone
weeklyDaily fields plus non-empty, unique, ascending ISO weekdays (Monday is 1)
cronA canonical five-field expression plus an explicit timeZone
rruleOne canonical DTSTART and one RRULE line

All seven stay authoritative; normalization preserves committed instants and does not convert cron into RRULE. Corrupt storage, invalid lines, keys inconsistent with task identity, and unsupported versions are all rejected before a task activates. A missing file starts from an empty domain; tasks whose target Session is missing remain visible in management, and reading a task never activates its Session.

scheduledAt and catch-up semantics

Every stored instant is canonical UTC, and decoding never recomputes it in the current zone.(source)

Every stored scheduledAt is a canonical RFC 3339 UTC instant with millisecond precision and years from 0001 to 9999. Decoding never recalculates it from current time zone data — which is why changing the system zone does not shift historical tasks.

Catch-up is "latest only": keep that committed lower bound, deliver the newest due instant once, then commit the first future instant. Exhausted rules leave the task in ended state rather than deleting it.

Fixed-rate catch-up is more explicit: downtime intervals merge rather than replay one by one. So "three days down, three messages on restart" should not happen.

Local calendar rules add two details: nonexistent wall-clock times are skipped, and overlapping times choose the earlier instant. Fixed intervals keep elapsed-time meaning. A one-shot delay may be shorter than a minute, but the per-task minimum delivery interval applies after the first delivery.

Cron and RRULE differ beyond style

Their matching semantics differ, so converting one into the other changes behavior.(source)

Cron input is { expression, time_zone } with five numeric fields in minute, hour, day-of-month, month, and weekday order. It supports *, single values, closed ranges, star or range steps, and comma lists; Sunday accepts 0 or 7 and normalizes to 0; names, macros, a seconds field, and "single value followed by a step" are rejected.

Cron keeps Vixie's date matching: when both date fields are restricted, either day-of-month or weekday matching suffices; when either field starts with * (step-bearing stars included), both value sets must match. Search is bounded by the 400-year Gregorian cycle and the four-digit UTC year range, and enabling rejects rules with no representable future instant.

RRULE accepts a bounded RFC 5545 subset: exactly two non-empty content lines, DTSTART then RRULE; start times use UTC Z or an explicit IANA TZID, rejecting floating local times, numeric offsets, date-only values, and extra lines. The engine is rrule 2.8.1 supporting MINUTELY through YEARLY, with COUNT=1 for one-shot delivery.

Validation happens before enumeration: SECONDLY, multiple BYSECOND values, and rules with more than 10,080 possible candidates in one frequency period are rejected. COUNT is 1 to 1,000 and cannot coexist with UNTIL; UNTIL is an absolute UTC datetime ending in Z; start and cutoff years are 0100 to 9999.

Two local-time details: a nonexistent local DTSTART is rejected, while later nonexistent local occurrences are skipped without consuming COUNT, and overlapping times choose the earlier instant.

Three delivery targets, defaulting to new_once

The target decides reuse or creation, and the default is not "new every time."(source)

  • session — delivers into an existing Session. Enablement checks inside the management FIFO that it exists, is not archived, and is not a delegated child; delivery rechecks archival.
  • new_once — reserves a Session id before first delivery, creates the Session when needed, then stores it as session and reuses it. Retries and restarts keep that reservation.
  • new — creates a Session per delivery, persisting pendingDelivery.targetSessionId before creation so a failed attempt reuses the same Session.

Omitting the target at creation defaults to new_once. Adding or replacing new or new_once targets requires the embedding environment to offer Session creation; when an SDK composition lacks that capability, those requests are rejected with invalid_rule before saving, while existing session targets keep working.

Creation cwd and agentPreset may be omitted and default to Host values. Created Sessions join a Workspace whose directory is registered (if any) and take the task title when they have none; new also appends the creation minute in the rule's time zone. Join or rename failures are logged but never block delivery.

Management operations and time edits

Edits are atomic patches, with optimistic concurrency through expectedUpdatedAt.(source)

Every caller uses the same ScheduleCreateRequest, ScheduleCatalogEntry, ScheduleTiming, and ScheduleEditRequest; there is no Session-bound management entry or second alias set.

Key operations: list defaults to 100 and caps at 500 with an optional active filter and non-negative offset; history reads saved deliveries without activating a Session, with limit from 1 to 100; edit atomically applies an update patch or delete by id; deleteInactive batch-deletes only ended tasks in one write, writing nothing for an empty set; run delivers immediately through normal admission without changing the scheduled instant or lifecycle.

Updates may replace title, instructions, typed timing, target, or active state, with omitted fields keeping their values. When the rule changes or is explicitly resumed, future instants are computed at FIFO acceptance time; equivalent timings and descriptive edits preserve the committed target. An already delivered one-shot task needs a new future time to resume; retargeting does not require converting the timing type.

expectedUpdatedAt is optional optimistic comparison: a string compares against the stored revision, explicit null compares against a missing revision, and a mismatch returns schedule_conflict. Editing a row without a revision creates one, and later revisions increase monotonically even if the clock moves backward. Cancellation is checked before a write starts, and a persistent write already begun does not roll back.

Host delivery and two crash windows

Inbox writes precede receipts, so a crash between stores can duplicate a delivery.(source)

One Host timer drives active tasks, and runtime plus management writes share one FIFO. Existing and reserved Sessions resolve through schedule/resolve-agent; tasks reusing a Session occupy an execution slot until the target Agent is idle, coalescing instants that occur meanwhile; new targets allow parallel executions. Duplicate records due at the same instant for the same existing Session share one message, while after and at deliver separately.

Scheduled and manual deliveries both respect the 60-second per-task minimum interval. newSessionIntervalSeconds can raise the interval for new targets by up to a week. When a stored successor instant keeps its interval, the lower bound is computed from the last occurrence; otherwise from the last confirmation, so delivery delay never moves the rule anchor.

Remember the crash window: the Session inbox persists before the task receipt, so a crash between the two stores can duplicate a delivery. The Host must be running. An active task pointing at a Session participates in that Session's archival admission, and the archive stop operation deletes those active tasks.

A receipt records scheduledAt, deliveredAt, messageId, and targetSessionId, and it confirms the persistent Session inbox write, not model completion. History stays in append order regardless of clock changes; confirmations append and trim within the same task commit, keeping at most 200 entries and 30 days while always preserving the newest receipt.

Verification: cross a time zone and a missed window

Test the zone boundary, the catch-up count, and target reuse together.(source)

  1. Create a daily 09:00 task in Asia/Shanghai and assert scheduledAt is UTC and maps back to exactly 09:00 locally.
  2. Change the system time zone, restart, read the task, and assert scheduledAt is unchanged.
  3. Cross three due instants while stopped, then recover and assert only the newest delivered, not three.
  4. Create an every 60-second task, change every_seconds, and assert the new anchor starts at edit acceptance time.
  5. Create a task with the default target, deliver twice, and assert both reuse the same Session id.
  6. Call edit with a stale expectedUpdatedAt and assert schedule_conflict with the task unmodified.

If step 3 yields several messages, first confirm the rule type is not at or after — one-shot types deliver separately by design.

For configuration, see schedule task configuration; for session binding problems, see schedule session binding.

One line to close: all seven types stay authoritative, scheduledAt is canonical UTC, cron never becomes RRULE, catch-up takes only the newest, targets default to reuse, and inbox-before-receipt allows duplicates.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Is DSH plugin cron converted into RRULE?

No. DSH plugin keeps the stored expression and time zone authoritative. DSH plugin reads, descriptive edits, retargeting, and restarts never convert a cron record into an RRULE.

Does DSH plugin replay every missed slot after downtime?

No. DSH plugin coalesces missed intervals. DSH plugin fixed-rate schedules merge downtime instead of replaying each slot, and the latest-only policy delivers just the newest due time once.

Does DSH plugin use 1 through 7 for weekdays?

Yes. DSH plugin weekly uses ISO weekdays with Monday as 1 and Sunday as 7. DSH plugin cron accepts 0 or 7 for Sunday and normalizes both to 0.

Does a DSH plugin session target recheck archival?

Yes. DSH plugin checks at both enablement and delivery. DSH plugin validates existence, non-archived state, and non-delegated-child status when enabling, then rechecks archival at delivery.

Related Terms

scheduledAt
scheduledAt is the stored canonical RFC 3339 UTC instant with millisecond precision and years from 0001 to 9999.— packages/schedule/schedule/src/types.ts
new_once
new_once is the default delivery target: it reserves a Session id before first delivery, creates when needed, then stores it as session and reuses it.— packages/schedule/schedule/src/types.ts
expectedUpdatedAt
expectedUpdatedAt is optional optimistic concurrency comparison; a mismatch returns schedule_conflict.— packages/schedule/schedule/src/types.ts
deliveryHistory
deliveryHistory is append-ordered delivery receipt history, capped at 200 entries and 30 days by default while keeping the newest receipt.— DeepSeek Harness reference - Host schedule

Sources