dsh-routines
Scheduled agents for DSH — run a prompt on a cron, get the digest where you already are.
dsh-routines is a plugin bundle for DeepSeek Harness. A routine is a named prompt + schedule + delivery stored as a plain YAML file — human-diffable, git-committable. The scheduler launches each due run through the headless runner as its own one-shot session (full session log = full audit, replay-able later by dsh-replay), then delivers a digest: the last assistant message when it is short, otherwise a one-shot summarizer call over the session log.
┌──────────────────────┐ every night 02:00 ┌──────────────────────────────┐
│ dsh --profile ops │ ─────────────────────▶ │ dsh --profile headless │
│ scheduler tick │ (own session, cwd │ "run the test suite, ..." │
│ reads .dsh/routines │ = routine cwd, │ approval policy: never │
│ /*.yaml │ approval: never) └──────────────┬───────────────┘
└──────────────────────┘ │ run record: status,
│ digest + run record │ digest, session id,
▼ │ denied approvals
.dsh/routines/runs/<runId>.json (+ .md) ──► file delivery (always on)
ctx.chatnode (optional) ──► chatnode delivery (soft dependency)Flagship demo — nightly test triage
A routine that runs your test suite at 2am, diagnoses the top failure, and leaves a digest in the project — then, with a conversation node installed, that digest lands in WeChat and you reply to approve follow-ups (v0.2; v0.1 delivers to file and chatnode when a node is installed).
# ~/work/projectx/.dsh/routines/nightly-tests.yaml
name: nightly-tests
schedule: "0 2 * * *" # 5-field cron; also accept "@daily", "every 4h"
timezone: Asia/Shanghai # explicit, no silent host-tz default
prompt: |
Run the test suite. If anything fails, diagnose the top failure
and draft a fix on a branch. Summarize in <10 lines.
cwd: ~/work/projectx
profile: headless # which DSH profile/plugin set the run uses
overlap: skip # skip | queue | cancel-previous
timeoutMin: 45
deliver:
- type: file # always on: digest written under .dsh/routines/runs/
- type: chatnode # optional: any installed conversation node (wechat…)$ dsh --profile ops routines list
nightly-tests active 0 2 * * * tz=Asia/Shanghai next=2026-08-15T02:00:00.000ZNext morning, the digest is waiting:
$ dsh --profile ops routines logs nightly-tests --limit 3
[completed] 2026-08-14T18:00:01.000Z 41213 ms session=session-2f7d…
tests: 3 failed of 412; top failure: flaky wait in auth.spec.ts — drafted fix on branch fix/auth-waitInstall
# 1. Create the profile that hosts the scheduler + CLI (installs this bundle).
# From the npm registry once published, or straight from this repository:
dsh plugin --profile ops add @dsh-routines/bundle # npm (when published)
dsh plugin --profile ops add github:Jesse-njx/dsh-routines # or: straight from GitHub
# 2. Keep it alive so schedules fire (daemon mode; Ctrl-C to stop).
dsh --profile opsRoutine runs boot the headless profile by default, which ships with DSH — no extra setup needed. A routine that needs another profile's plugin set sets profile: <name>; that profile must be one-shot-capable (include the headless bundle, or install this bundle into it as well — the run overlay disables the nested scheduler either way).
Scheduler host
The scheduler ticks inside whatever profile the bundle is installed into, so you can also add the bundle to your main web profile and routines fire while the web app runs:
dsh plugin --profile web add @dsh-routines/bundleKeep the process alive for schedules to fire; dsh --profile ops with no inner arguments is the intended daemon form (the CLI stays silent and the scheduler owns process lifetime).
Routine files
Routines live in two watched directories (hot-reload on change; invalid files are reported, never crash the store):
| Directory | Scope |
|---|---|
<cwd>/.dsh/routines/*.yaml | Project routines (override global on name) |
~/.dsh/routines/*.yaml | Global routines |
| Field | Default | Meaning |
|---|---|---|
name | — (required) | [a-z0-9][a-z0-9-]*, ≤ 64 chars |
schedule | — (required) | 0 2 * * *, @daily, @hourly, @weekly, @monthly, @yearly, every 4h, every 30m |
timezone | UTC | IANA zone for schedule math (never the host zone) |
prompt | — (required) | The task the headless run executes |
cwd | operator cwd | Working directory of the run; also where its digest lands |
profile | headless | DSH profile the run boots |
overlap | skip | skip (never stack two agents on one repo), queue (run after the current one), cancel-previous |
timeoutMin | 45 | Hard stop; a wedged 2am agent must not still hold the repo at 9am |
deliver | [{type: file}] | Digest delivery channels |
Cron fields support *, step suffixes (*/15), ranges (9-17), lists (0,30), ?, and month/day names. When both day-of-month and day-of-week are restricted, a day matches if either matches (Vixie cron semantics).
Scheduler bookkeeping (paused set, last-run anchors) lives in <cwd>/.dsh/routines/state.json.
CLI
dsh --profile ops routines <command>
| Command | Description |
|---|---|
list | routines with schedule, pause state, next run |
run <name> | manual trigger (runs now; prints the digest and exits) |
pause <name> / resume <name> | stop / restart scheduled runs |
logs <name> [--limit n] | recent run records: status, duration, digest, session id |
Run records are JSON files under <routine.cwd>/.dsh/routines/runs/<runId>.json, with a human-readable <runId>.md digest next to them. run is also the manual trigger for testing a routine before you trust its schedule.
Safety defaults
Scheduled agents run unattended, so each run subprocess is patched to:
- Auto-deny anything that would prompt — the run overlay forces the approval policy to
never(sandbox mode stays whatever the profile inherits, normallyworkspace-write). Denied requests are collected into the run record (denied) and surface in the digest. - Never schedule nested runs — the run overlay disables the scheduler row inside the run profile.
- Never crash the scheduler — delivery failures, summarizer failures, and spawn failures are recorded on the run record, not thrown.
Missed runs (laptop asleep): at most one catch-up run fires on wake, never a backlog replay.
Delivery
- file (always on): the run record + digest markdown under
.dsh/routines/runs/. - chatnode (optional): digests are sent through a
ctx.chatnodeservice ({ send(input: { text, title? }): Promise<void> }) when one is installed; otherwise the delivery is recorded asnot-installedand the run still completes. A future@dsh-cowork/chatnode-wechatexposing that service lights this up automatically.
Architecture
One bundle, three plugins (+ a run driver), all installable as subpaths:
| Module | Role |
|---|---|
@dsh-routines/bundle/store | watches .dsh/routines/*.yaml (project + global), validates, hot-reloads, owns durable state |
@dsh-routines/bundle/scheduler | registers due routines on ctx.jobs (kind routine); owns overlap, missed-run, and timeout semantics |
@dsh-routines/bundle/cli | the dsh routines ... command line |
@dsh-routines/bundle/run | child-side driver injected into each one-shot run via a generated --patch overlay; writes the run record and digest |
Runs boot dsh --profile <routine.profile> --patch <generated overlay> -- "<prompt>" with the routine's cwd as the workspace. The overlay disables the stock headless runner, mounts the run driver on the same task service, and forces the unattended approval policy — so the run keeps the full headless experience (fresh persisted session, provider selection) while writing the audit record only dsh-routines knows how to read.
Development
pnpm install
pnpm build # tsc -> lib/
pnpm test # node --test (46 tests: cron, scheduler matrix, store, run, cli, e2e)The e2e test boots a real dsh subprocess against a scripted mock LLM adapter (no network, no credentials) in a throwaway DSH_HOME, so the whole pipeline — store → scheduler → jobs → subprocess → run driver → digest → record — is exercised in CI.
Promo
promo/ holds a self-contained 60-second promo deck for screen recording: slideshow.html (keyboard-advanceable, 1280×720, no external assets) and narration.txt (a timed read-aloud script). Open slideshow.html and press →/space to advance.
Non-goals
Cloud execution (local machine only; the missed-run policy handles an asleep laptop honestly), routine marketplaces, sub-minute schedules.
License
MIT
