dsh-cron
English | 中文
A durable calendar Trigger adapter for DSH Automation. It turns one-shot or recurring schedule occurrences into idempotent fresh-Session Runs. It never executes an Agent turn itself.
Responsibility boundary
- dsh-cron owns schedule parsing, timezone calculation, durable occurrence identity, catch-up policy, and the task-center UI.
- dsh-automation owns the Run queue, canonical fresh Sessions, cross-worker concurrency, cancellation, explicit retries, event history, retention, and crash recovery.
- dsh-webhook is the equivalent event-driven Trigger adapter and optionally provides outbound settlement callbacks.
Install
Requires Node.js 24 or newer, DSH 0.1.2-rc.1 or newer within the 0.1.x line, and dsh-automation 0.2.x.
Install dsh-automation first, then the adapter:
dsh plugin --profile web add github:cofy-x/dsh-automation
dsh plugin --profile web add github:omdsh-dev/dsh-cron
The plugin contributes a browser task center through its dsh.client manifest and works in headless profiles through tools, commands, and RPC.
Scheduling semantics
Supported schedules:
- five-field cron: minute, hour, day-of-month, month, day-of-week;
- one-shot RFC 3339
at timestamps with an explicit offset or Z;
- IANA time zones with daylight-saving-aware occurrence calculation.
For every calendar occurrence, the scheduler persists a run record and advances the schedule before submitting Automation. The stable identity and key are derived from the job id and scheduled instant. If the process dies after Automation commits but before the source store records its Run id, restart submits the same key and receives the same Run.
Missed recurring occurrences use an explicit latest-only catch-up policy: the newest due instant runs once, older backlog is not replayed. A one-shot remains as durable history after it fires. Pausing preserves the schedule; resuming advances recurring schedules past the current time.
Each job uses concurrency key cron:<job-id> with a configurable limit (currently one by default). dsh-automation enforces the limit transactionally across every worker and process.
Usage
Model tools:
cron_add — create a recurring or one-shot job;cron_update — pause or resume;cron_list — inspect schedules, occurrences, linked Runs, and outcomes;cron_remove — delete a job.
Commands:
/cron add 0 9 * * 1-5 Summarize the project status
/cron add tz=Asia/Shanghai 30 18 * * 5 Prepare the weekly report
/cron add-at 2026-09-01T09:00:00+08:00 Run the release checklist
/cron pause cron-1
/cron resume cron-1
/cron remove cron-1
Jobs created by a command or model tool capture the creating Session's absolute workspace as a fresh Automation target. Browser/API jobs must send cwd or inherit defaultCwd. Migrated legacy jobs without either are safely paused with a migrationIssue until retargeted.
Durable reconciliation
Occurrence records progress from submitting to the linked Automation state and terminal projection. They retain:
- deterministic
occurrenceId, scheduledAt, and idempotencyKey;
- linked
automationRunId and current Run state;
- terminal completion time, outcome, result excerpt, or error.
The adapter consumes the durable Automation feed with checkpoint cron.adapter.v1. On an expired cursor, it refreshes every linked Run by id and resumes at the published prune watermark. Terminal settlement is emitted only once for optional callback integration.
The source store keeps bounded terminal history but never trims active occurrence records. Schema v1 migrates to v2 on load; old lastRun data remains readable as a legacy occurrence.
Configuration
| Key | Default | Meaning |
|---|
dataDir | $DSH_HOME/cron | durable job store and scheduler lock directory |
defaultTimeZone | host zone | zone used when a cron expression omits one |
maxJobs | 64 | maximum active jobs |
minIntervalMinutes | 1 | minimum recurring interval |
defaultCwd | none | absolute fallback workspace for browser/API jobs |
reconcilePollMs | 1000 | Automation event-feed poll interval |
maxRunHistory | 100 | retained terminal occurrences per job |
Only the scheduler-lock holder arms timers, submits pending occurrences, and reconciles the feed. Other processes sharing the same Harness home expose management services and can take over after the holder exits.
Management writes use a separate short-lived cross-process lock, collision-free sequence sidecar, and record-level three-way merge. A process adopts peer additions and untouched edits without resurrecting deletions; prolonged lock contention fails closed instead of overwriting peer state.
The adapter requires the public dsh-automation >=0.2.0-alpha.0 <0.3.0 service contract. It does not import private dsh-automation source and requires no deepseek-harness modification.
Development
pnpm install
pnpm run verify:self-contained
pnpm run typecheck
pnpm test
pnpm run build
pnpm run prepare
License
MIT
