dsh-scheduled

Durable heartbeat and cron automations for DeepSeek Harness.

dsh-scheduled is a global automation plugin: one installation manages schedules across projects and sessions. This is intentionally different from DSH's built-in dsh-schedule, which stores session-local reminders in the session event log.

Features

• Heartbeat resumes a saved DSH conversation and follows up in that thread.
• Cron creates a fresh project session for each run, optionally in an isolated Git worktree.
• RFC 5545 recurrence rules with IANA time zones and DST-aware wall-clock scheduling.
• Durable automation and run history in one atomic JSON file.
• Overlap prevention, skipped-occurrence recording, interruption recovery after restart, and explicit error codes.
• Agent tool plus a Web Settings page backed by the same Host RPC service.
• Cordis-owned timers and agent-scoped tool registration so plugin effects are disposed with DSH lifecycles.

Install

The package is a DSH bundle and can be installed from the public GitHub repository with the normal plugin command. Pin a commit for reproducible installs:

dsh plugin --profile web add github:ylxmf2005/dsh-scheduled#56c067b

The v0.1.4 release also includes a prebuilt tarball if you do not want an install-time build:

dsh plugin --profile web add https://github.com/ylxmf2005/dsh-scheduled/releases/download/v0.1.4/dsh-scheduled-0.1.4.tgz

For a GitHub checkout, allow the package build in the profile's pnpm-workspace.yaml:

dsh plugin --profile web add github:ylxmf2005/dsh-scheduled#<commit>

allowBuilds:
  dsh-scheduled: true

Git installs fetch source and run the package's self-contained prepare build. Only allow builds from source you trust. Restart DSH after installation, then open Settings > Plugins > Scheduled.

Usage

Schedules use RFC 5545 text. Include DTSTART and TZID when wall-clock timing matters:

DTSTART;TZID=Asia/Shanghai:20260822T090000
RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0

Heartbeat automations need a target session. Cron automations need a project path. The automation_update tool exposes create, list, view, update, delete, run, runs, and mark_read operations; the Settings page exposes the same operations through Host RPC.

Failed runs are recorded and do not retry automatically. The next recurrence remains scheduled unless the automation is paused or completed.

Persistence and retention

The plugin stores global automation state at $DSH_HOME/automations/automations.json by default. Global persistence is deliberate: schedules can resume cold sessions and create runs across projects, which cannot be represented by one session's event log. Writes use a temporary file and rename, and startup fails loudly when the store is corrupt rather than silently discarding schedules.

Cron worktrees are retained by default so the run's DSH session remains inspectable after completion. Remove them only after reviewing the associated run and any changes made by the agent.

Development

Requires Node.js >=22.19.0 and pnpm.

pnpm install
pnpm test
pnpm run typecheck
pnpm run build
pnpm pack --dry-run

pnpm run prepare/npm run prepare builds the same self-contained artifacts used by GitHub installs. See CONTRIBUTING.md for the contribution workflow and CHANGELOG.md for release history.

License

MIT