# dsh-scheduled

Durable heartbeat and cron automations for [DeepSeek Harness](https://github.com/deepseek-ai/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:

```bash
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:

```bash
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`:

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

```yaml
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:

```text
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.

```bash
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](CONTRIBUTING.md) for the contribution workflow and [CHANGELOG.md](CHANGELOG.md) for release history.

## License

MIT