@soffits/dsh-cron-jobs 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,7 +10,7 @@ DSH's built-in Schedule delivers a prompt to an agent session, so every tick sta
10
10
 
11
11
  A job's result can be **delivered**: the woken agent's final answer, or a command's output and failures, is handed to another plugin that sends it on, such as a chat bot. This plugin knows no channel itself; any plugin that provides a small `send` method can be one (see [Result delivery](#result-delivery)).
12
12
 
13
- Jobs run on cron expressions, RFC 5545 RRULE schedules, or once at a given time. They come from the plugin config, or an agent creates them from a conversation with the plugin's tools ("remind me here tomorrow at 9", "check this every Monday until January"). A **Cron tasks** page in the Web GUI shows every job and its recent runs, and lets you run a job now, pause it, or delete one an agent created.
13
+ Jobs run on cron expressions, RFC 5545 RRULE schedules, or once at a given time, and they can also run on **events** instead of polling: any script, hook or CLI can emit one with `dsh-cron-event <channel>`, and the plugin can keep long-running **watchers** (a mailbox push stream, a notification feed) whose output lines are events (see [Events](#events)). Jobs come from the plugin config, or an agent creates them from a conversation with the plugin's tools ("remind me here tomorrow at 9", "check this every Monday until January"). A **Cron tasks** page in the Web GUI shows every job and its recent runs, and lets you run a job now, pause it, or delete one an agent created.
14
14
 
15
15
  ## Install
16
16
 
@@ -91,7 +91,8 @@ Config jobs live in the config of the `cron-jobs` row. Add an override to your p
91
91
  | Field | Meaning |
92
92
  |---|---|
93
93
  | `name` | Job name, used in logs and session titles. Must be unique. |
94
- | `cron` | Cron expression: 5 fields, or 6 with seconds first. Parsed by [croner](https://github.com/hexagon/croner), which handles daylight-saving changes like Vixie cron: a fixed time skipped by a spring forward runs at the first valid time after the gap, a fixed time repeated by a fall back runs once, and patterns with several hours, minutes or seconds run on both repeated occurrences. Set exactly one of `cron`, `rrule` and `at`. |
94
+ | `cron` | Cron expression: 5 fields, or 6 with seconds first. Parsed by [croner](https://github.com/hexagon/croner), which handles daylight-saving changes like Vixie cron: a fixed time skipped by a spring forward runs at the first valid time after the gap, a fixed time repeated by a fall back runs once, and patterns with several hours, minutes or seconds run on both repeated occurrences. Set exactly one of `cron`, `rrule` and `at`, or none when the job has `on`. |
95
+ | `on` | Event channel patterns that start a run, such as `[mail.sakina, alerts.*]`. See [Events](#events). |
95
96
  | `rrule` | RFC 5545 schedule: a `DTSTART` line and an `RRULE` line. The time zone comes from `DTSTART` (`TZID=...`, or `Z` for UTC). See [Schedules](#schedules). |
96
97
  | `at` | Run once at this time: ISO 8601 with an offset, or a local date-time read in `timeZone`. |
97
98
  | `timeZone` | IANA time zone for the cron expression or an `at` without offset. The Host's zone when empty. |
@@ -120,12 +121,15 @@ Next to `jobs`, the row also takes:
120
121
  | `deliver` | Default delivery target, `{ via, to }`, for jobs that do not set `deliver`. Unset: results are not delivered. |
121
122
  | `historyRecords` | Runs kept per job for the Cron tasks page. Default 50, at most 1000. |
122
123
  | `runLog` | Optional JSON Lines file of run starts and ends, see below. |
124
+ | `watchers` | Long-running commands whose output lines are events: `[{ id, channel, command, cwd, enabled }]`. See [Watchers](#watchers). |
125
+ | `events.coalesceSeconds` | Events for one job that arrive within this many seconds of the first start one run. Default 30. |
126
+ | `events.maxRunsPerHour` | Most event-started runs of one job in any hour; past that, events wait and run together. Default 6; `0` means no cap. |
123
127
 
124
128
  ## How runs work
125
129
 
126
130
  - One run of a job at a time: if a tick arrives while the previous run is still going, the tick is skipped and logged.
127
131
  - Start, exit status, duration and a short tail of stdout and stderr go to the DSH log under `cron-jobs`. Sending the result anywhere else is what [Result delivery](#result-delivery) is for.
128
- - Set `runLog` (next to `jobs`) to a file path to also keep that record as JSON Lines: one `start` line per run, one `end` line with `status`, `outcome`, `exitCode`, `durationMs`, the output tails and the delivery state, a `delivery` line when a result waits for its channel (`waiting`), is left for the next start (`pending`), or has been delivered or not (`sent`, `silent`, `failed`), a `skipped` line for a skipped tick, an `overdue` line (with `dueAt` and `lateMs`) when a tick did not start on time and the watchdog ran it late, and `scheduler-start` / `scheduler-stop` lines (with `job: null`) when the scheduler starts or stops, so a gap in the log can be told apart from a lost tick. A `start` with no `end` means DSH stopped during the run. The file is only appended to; rotate it yourself if it grows.
132
+ - Set `runLog` (next to `jobs`) to a file path to also keep that record as JSON Lines: one `start` line per run, one `end` line with `status`, `outcome`, `exitCode`, `durationMs`, the output tails and the delivery state, a `delivery` line when a result waits for its channel (`waiting`), is left for the next start (`pending`), or has been delivered or not (`sent`, `silent`, `failed`), a `skipped` line for a skipped tick, an `overdue` line (with `dueAt` and `lateMs`) when a tick did not start on time and the watchdog ran it late, and `scheduler-start` / `scheduler-stop` lines (with `job: null`) when the scheduler starts or stops, so a gap in the log can be told apart from a lost tick. Events add an `event` line per event (`channel`, `source`, the `matched` job ids, or `duplicate`), and watchers `watcher-start`, `watcher-exit` (exit code, run time, stderr tail), `watcher-down` and `watcher-up` lines. An event run's `start` line has `trigger: event` and the events' count and channels. A `start` with no `end` means DSH stopped during the run. The file is only appended to; rotate it yourself if it grows.
129
133
  - Ticks of config jobs missed while DSH is down are not caught up; the next tick runs normally. While DSH runs, a watchdog checks every minute that each job's next run is not more than a minute in the past; a tick whose timer was lost runs late instead of being missed. (Jobs created from a conversation catch up once, see below.)
130
134
  - Unloading the plugin (stopping DSH or changing its config) stops the timers and terminates running commands.
131
135
 
@@ -163,6 +167,12 @@ Where results go is decided per job: its own `deliver` (or `false`), otherwise n
163
167
 
164
168
  Each run's delivery shows on the Cron tasks page and in the run log: not sent yet (waiting for the answer or for the channel), sent, nothing to send, or not sent with the reason. A delivery still waiting when DSH stops or the plugin reloads, whether for a turn that is still running or for a channel that is not there, is picked up and delivered after the next start.
165
169
 
170
+ ### Runs cut off by a restart
171
+
172
+ A woken turn that DSH itself stops before it finishes (a restart, or a reload that disposes the session's agent) is run again once. A turn a person stopped, or one that failed, is not. The cut-off turn delivers nothing; 30 seconds after DSH is back (or after the plugin notices, if it was running all along), the plugin sends a short follow-up into the same session saying the earlier turn was cut off and asking the agent to finish the job without repeating what is done. The session already holds the job's prompt, command output and events, and whatever the cut-off turn did. The rerun's answer is delivered like any other.
173
+
174
+ The rerun is skipped, with the reason in the run history and a `rerun-skipped` run-log line, when the cut-off run started more than 2 hours ago, a later run of the job has woken the agent since, the job's next run is less than 15 minutes away, or the job is paused, disabled or deleted. A session the job opened for itself that a person has since taken over is left alone: the rerun fails with a note to the delivery target. A rerun that is cut off too is not run again. The run log marks the cut-off with a `cut-off` line, and the rerun's `start` line carries `rerunOf`.
175
+
166
176
  ### Answer checks
167
177
 
168
178
  A job can name a command, `agent.answerCheck` (or `answerCheck` in the tools), that looks at the agent's final answer while the turn can still change it. When the turn that the job's prompt started is about to close, the command runs with the answer on stdin, in the session's working directory, with a 60-second limit. Empty stdout passes the answer. Anything it prints goes back into the same turn as a message asking for a rewrite, and the agent's next answer is the one delivered. Each run is steered at most once, so a check that never passes cannot keep a turn going. Empty answers, `[SILENT]` and answers with only `MEDIA:` lines are not checked. A command that fails or times out lets the answer through.
@@ -211,16 +221,79 @@ and point a job at it with `deliver: { via: myChannel, to: <address> }`.
211
221
 
212
222
  When an RRULE or one-time schedule has no more runs, the job's state becomes **ended**. It stays listed until it is deleted (or, for config jobs, removed from the config).
213
223
 
224
+ ## Events
225
+
226
+ A job can run when something happens instead of checking on a timer. Give it `on`, a list of channel patterns, with or without a schedule:
227
+
228
+ ```yaml
229
+ - name: Mailbox
230
+ on: [mail.me]
231
+ cron: '0 */2 * * *' # slow safety net in case an event is missed
232
+ command: ./mail-gate.sh
233
+ agent:
234
+ prompt: Handle the new mail.
235
+ ```
236
+
237
+ **Channels** are dot-separated names of letters, digits, `_`, `:` and `-`, such as `mail.me`, `ci.run.123` or `dsh.started`. In a pattern, `*` matches any characters, dots included, so `alerts.*` matches `alerts.disk` and `alerts.komodo.down`.
238
+
239
+ **Emitting an event.** The package installs a small CLI:
240
+
241
+ ```sh
242
+ dsh-cron-event ci.run.123 --data '{"conclusion": "success"}'
243
+ gh run watch 123 --exit-status; dsh-cron-event ci.run.123 --data "{\"exit\": $?}"
244
+ echo '{"subject": "hi"}' | dsh-cron-event mail.me --data -
245
+ ```
246
+
247
+ It writes one file into the plugin's inbox, `$DSH_HOME/cron-jobs/events/` (mode 700), and waits up to ten seconds for DSH to take it, printing the ids of the jobs it matched. No port, token or network path into DSH is needed, and an event written while DSH is down waits there and is taken at the next start. `--id <key>` drops a second event with the same channel and key within an hour; `--no-wait` returns at once; `--text` sends plain text instead of JSON. Exit code 3 means DSH did not take it in time (it stays queued). The CLI is in the profile's `node_modules/.bin`; link it somewhere on `PATH` to call it by name.
248
+
249
+ **What a run sees.** Events for one job that arrive within `events.coalesceSeconds` (30 s) of the first one are gathered, and the job runs once with all of them:
250
+
251
+ - The command gets them on stdin as one JSON document, `{"trigger": "event", "events": [{"channel", "at", "data" or "text", "key", "source"}], "dropped": 0}`, and every command gets `DSH_CRON_TRIGGER` (`schedule`, `manual` or `event`) and `DSH_CRON_JOB` in its environment. A gate still decides whether to wake the agent.
252
+ - The agent prompt gets the events appended, one JSON line each, in a block marked as untrusted data from outside DSH. An event is a hint: the job should read the truth from its source (the mailbox, the CI run), so a forged or garbled event costs one wasted run, and a message's subject never reaches the agent as an instruction.
253
+
254
+ If the job is still running when its batch is ready, it runs once more as soon as the current run ends, with every event gathered meanwhile. A scheduled tick that finds the job running is still skipped as before. At most `events.maxRunsPerHour` (6) event runs of one job start in any hour; past that, events wait and run together when the oldest of those runs is an hour old, so a stuck feed cannot start hundreds of runs. A paused, ended or disabled job ignores events. The run history and the Cron tasks page show event runs with their channels.
255
+
256
+ **`once`** (tools only) ends a job after its first run that was not started by hand. With `on: [dsh.started]` it waits for the next DSH start.
257
+
258
+ **Built-in event.** `dsh.started` is emitted once per DSH process, when the scheduler first starts (not on a plugin reload). A one-off "check DSH after the restart" job becomes `on: [dsh.started], once: true`, instead of a guessed time.
259
+
260
+ **Delivery and safety.** An inbox file is kept (as `.processing`) until every run it started has begun, so a restart in between reads it again. Events from watchers are not kept; each watcher catches up from its own cursor when it starts (below). Either way the job's slower schedule is the safety net for anything missed.
261
+
262
+ ### Watchers
263
+
264
+ A watcher is a long-running command the plugin starts with the scheduler, restarts when it exits, and stops on unload. Each stdout line is an event on the watcher's channel:
265
+
266
+ - a JSON object line is the event's data, and its string `id` field, if any, is the dedupe key;
267
+ - any other non-empty line is the event's text;
268
+ - `{"wakeAgent": false}` lines are ignored.
269
+
270
+ A watcher that exits is restarted after 1 s, doubling up to 5 minutes, and back to 1 s once a run lasted a minute. If it has not managed to stay up for a minute in 15 minutes, one note goes to the row's `deliver` target, and one more when it works again; exits, stderr tails and these notes are in the run log. The command runs with `bash -c` in its own process group, with `DSH_CRON_WATCHER` (its id), `DSH_CRON_CHANNEL` and `DSH_CRON_STATE_DIR` (`$DSH_HOME/cron-jobs/watchers/<id>`, a directory for its cursor) in its environment.
271
+
272
+ Watchers come from the row's `watchers` list, or from a conversation with the `cron_job_watch` tool (`create`, `delete`, `list`), which keeps them in DSH storage. A tool-made watcher can be `once`: it runs one time and removes itself when it exits, for a one-off wait that has to survive a DSH restart:
273
+
274
+ ```
275
+ cron_job_watch create id=ci-123 channel=ci.123 once=true
276
+ command='gh run watch 123 --exit-status >/dev/null; echo "{\"exit\": $?}"'
277
+ cron_job_create title="Report CI 123" target=this_session on=["ci.123"] once=true prompt="CI run 123 finished; check it and tell me."
278
+ ```
279
+
280
+ A good watcher keeps a cursor (a JMAP state string, an IMAP UIDNEXT, a feed's last message id) in `DSH_CRON_STATE_DIR`, prints one line at startup when something changed while it was down, and exits on any error or a connection that went silent, leaving the restart to the plugin. Some sources that fit:
281
+
282
+ - **JMAP mail** (RFC 8620 EventSource, served by Stalwart, Fastmail and others): stream `eventSourceUrl` with `types=EmailDelivery` and print a line per `state` push.
283
+ - **IMAP IDLE**: [goimapnotify](https://gitlab.com/shackra/goimapnotify) with `onNewMail: echo new`.
284
+ - **ntfy**: `curl -sN 'https://ntfy.sh/<topic>,<topic>/json?since=<last id>'`, printing the `message` events.
285
+
214
286
  ## Jobs created from a conversation
215
287
 
216
- The `cron-jobs-tools` row registers four tools. Their names start with `cron_job` by default; the row's `prefix` setting changes that (`prefix: schedule` gives `schedule_create` and so on, the names of DSH's built-in Schedule tools, for use in its place).
288
+ The `cron-jobs-tools` row registers five tools. Their names start with `cron_job` by default; the row's `prefix` setting changes that (`prefix: schedule` gives `schedule_create` and so on, the names of DSH's built-in Schedule tools, for use in its place).
217
289
 
218
290
  | Tool | What it does |
219
291
  |---|---|
220
- | `cron_job_create` | Create a job: a title, a prompt and/or a command, exactly one of `cron`, `rrule` and `at` (with `timeZone` where needed), where the prompt goes, and optionally where the result is delivered and which model its sessions use. |
221
- | `cron_job_edit` | `update` the given fields, `pause`, `resume` (continues from now), or `delete` a job by id. |
292
+ | `cron_job_create` | Create a job: a title, a prompt and/or a command, one of `cron`, `rrule` and `at` (with `timeZone` where needed) and/or `on` (event channels), where the prompt goes, and optionally `once`, where the result is delivered and which model its sessions use. |
293
+ | `cron_job_edit` | `update` the given fields, `pause`, `resume` (continues from now), or `delete` a job by id. An empty `cron`, `rrule` or `at` removes the schedule of a job with `on`; an empty `on` removes its subscriptions. |
222
294
  | `cron_job_list` | Every job, from the config and from tools, with its id, state, schedule, next run, target and last run. |
223
295
  | `cron_job_view` | One job's full definition and its five latest runs. |
296
+ | `cron_job_watch` | `create`, `delete` or `list` [watchers](#watchers). |
224
297
 
225
298
  A new job takes the calling session's working directory and agent preset, so a job created from a session in `/home/me/project` runs its command there and opens its sessions there. `cwd` sets another directory.
226
299
 
@@ -247,7 +320,7 @@ A delegated subagent can use the tools, but its own session cannot be a target,
247
320
  The Web GUI gets a **Cron tasks** entry in the sidebar, laid out like DSH's own Automation tasks page:
248
321
 
249
322
  - The list shows every job with its state (active, paused, off in config, invalid, or ended), its schedule and time zone, the next run, and the result of the last run. Jobs an agent created are marked "Created by an agent". Filter by state or search by name, command or prompt. The page refreshes every few seconds while it is visible.
250
- - Selecting a job opens its detail. **Settings** shows the job read-only (schedule, what it does, command, directory, time limit, where the prompt goes, where the result is delivered, and for jobs with a prompt the agent preset, session directory and where it came from, auto-archive, session reuse and prompt; for jobs an agent created, when and from which session). **Runs** lists the saved runs, newest first: start time, what started it (schedule or Run now), duration, exit code or other outcome, the woken session with a link that opens it, whether the session was reused, its archive state, the delivery result, and the tails of stdout and stderr.
323
+ - Selecting a job opens its detail. **Settings** shows the job read-only (schedule, what it does, command, directory, time limit, where the prompt goes, where the result is delivered, and for jobs with a prompt the agent preset, session directory and where it came from, auto-archive, session reuse and prompt; for jobs an agent created, when and from which session). **Runs** lists the saved runs, newest first: start time, what started it (schedule, Run now, or events with their channels), duration, exit code or other outcome, the woken session with a link that opens it, whether the session was reused, its archive state, the delivery result, and the tails of stdout and stderr.
251
324
  - The pause button pauses or resumes the job's schedule. **Run now** in the `⋯` menu starts one run immediately; it is refused while the job is already running, and it does not move the schedule. **Delete** in the same menu removes a job an agent created, with its run history. A job with a prompt has a footer link to its latest session.
252
325
 
253
326
  The page does not create or edit jobs: config jobs are edited in the config, the others through the tools.
@@ -0,0 +1,101 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Emit an event for dsh-cron-jobs: every job whose `on` matches the channel
4
+ * runs. The event goes through the plugin's inbox directory under
5
+ * $DSH_HOME/cron-jobs/events, so it needs no port or token, and it waits
6
+ * there while DSH is not running.
7
+ */
8
+ import { readFileSync } from 'node:fs'
9
+ import { parseArgs } from 'node:util'
10
+ import { defaultEventDir, isChannel } from '../src/events.js'
11
+ import { enqueueEvent, waitForEventResult } from '../src/spool.js'
12
+
13
+ const usage = `Usage: dsh-cron-event <channel> [--data <json> | --data - | --text <text>]
14
+ [--id <dedupe key>] [--source <label>] [--no-wait] [--timeout <seconds>]
15
+
16
+ Emits one event on <channel> (dot-separated names, such as mail.sakina or
17
+ ci.run.123). Jobs whose on patterns match it run once the events around it are
18
+ gathered (about 30 s). The event is a hint: jobs check the source themselves.
19
+
20
+ --data <json> JSON data for the event; "-" reads it from stdin (JSON, or
21
+ plain text when it does not parse)
22
+ --text <text> plain text instead of data
23
+ --id <key> dedupe key: a second event with the same channel and key
24
+ within an hour is dropped
25
+ --source <label> who sent it, shown to the job
26
+ --no-wait return at once instead of waiting for DSH to take it
27
+ --timeout <s> how long to wait (default 10)
28
+
29
+ Prints {"matched": [job ids]} when DSH took the event.
30
+ Exit codes: 0 taken (or queued with --no-wait), 1 refused, 2 bad arguments,
31
+ 3 still queued after the timeout (DSH takes it once it runs).`
32
+
33
+ let options
34
+ try {
35
+ options = parseArgs({
36
+ allowPositionals: true,
37
+ options: {
38
+ data: { type: 'string', short: 'd' },
39
+ text: { type: 'string', short: 't' },
40
+ id: { type: 'string' },
41
+ source: { type: 'string', short: 's' },
42
+ 'no-wait': { type: 'boolean' },
43
+ timeout: { type: 'string' },
44
+ help: { type: 'boolean', short: 'h' },
45
+ },
46
+ })
47
+ } catch (error) {
48
+ process.stderr.write(`${error.message}\n\n${usage}\n`)
49
+ process.exit(2)
50
+ }
51
+ const { values, positionals } = options
52
+ if (values.help) {
53
+ process.stdout.write(`${usage}\n`)
54
+ process.exit(0)
55
+ }
56
+ const fail = (message) => {
57
+ process.stderr.write(`${message}\n\n${usage}\n`)
58
+ process.exit(2)
59
+ }
60
+ if (positionals.length !== 1) fail('Give exactly one channel.')
61
+ const channel = positionals[0].trim()
62
+ if (!isChannel(channel)) fail(`${JSON.stringify(channel)} is not a channel name: dot-separated names of letters, digits, _ : -`)
63
+ if (values.data !== undefined && values.text !== undefined) fail('Give --data or --text, not both.')
64
+
65
+ const event = { channel }
66
+ if (values.data === '-') {
67
+ const raw = readFileSync(0, 'utf8')
68
+ try {
69
+ event.data = JSON.parse(raw)
70
+ } catch {
71
+ event.text = raw
72
+ }
73
+ } else if (values.data !== undefined) {
74
+ try {
75
+ event.data = JSON.parse(values.data)
76
+ } catch (error) {
77
+ fail(`--data is not JSON: ${error.message}`)
78
+ }
79
+ }
80
+ if (values.text !== undefined) event.text = values.text
81
+ if (values.id !== undefined && values.id.trim() !== '') event.key = values.id.trim()
82
+ event.source = values.source?.trim() || 'dsh-cron-event'
83
+
84
+ const dir = defaultEventDir()
85
+ const wait = !values['no-wait']
86
+ const id = await enqueueEvent(event, { dir, wait })
87
+ if (!wait) {
88
+ process.stdout.write(`${JSON.stringify({ queued: id })}\n`)
89
+ process.exit(0)
90
+ }
91
+ const seconds = Number(values.timeout ?? 10)
92
+ const result = await waitForEventResult(id, { dir, timeoutMs: (Number.isFinite(seconds) && seconds > 0 ? seconds : 10) * 1000 })
93
+ if (result === undefined) {
94
+ process.stderr.write(`Still queued as ${id}: DSH did not take it in time. It is taken once DSH runs.\n`)
95
+ process.exit(3)
96
+ }
97
+ if (!result.ok) {
98
+ process.stderr.write(`${result.error}\n`)
99
+ process.exit(1)
100
+ }
101
+ process.stdout.write(`${JSON.stringify({ matched: result.matched ?? [], ...(result.duplicate ? { duplicate: true } : {}) })}\n`)
package/client.js CHANGED
@@ -61,6 +61,7 @@ window.__ModuleLoader__.load({
61
61
  'detail.close': 'Close',
62
62
  'detail.nextRun': 'Next run ',
63
63
  'detail.noNextRun': 'No upcoming run',
64
+ 'detail.onEvents': 'Runs when an event arrives on {channels}',
64
65
  'detail.pause': 'Pause schedule',
65
66
  'detail.resume': 'Resume schedule',
66
67
  'detail.pauseUnavailable': 'Turned off in the plugin config',
@@ -80,6 +81,12 @@ window.__ModuleLoader__.load({
80
81
  'notice.running': 'Running since {time} ({trigger}).',
81
82
  'notice.memory': 'Run history is kept in memory only because DSH storage is unavailable; it is lost on restart.',
82
83
  'field.schedule': 'Schedule',
84
+ 'field.scheduleNone': 'None: runs on events only',
85
+ 'field.on': 'Runs on events',
86
+ 'field.once': 'Runs once',
87
+ 'field.onceValue': 'Ends after its first run that was not started by hand',
88
+ 'field.pendingEvents': 'Waiting events',
89
+ 'field.pendingEventsValue': '{count}, run at {time}',
83
90
  'field.timeZone': 'Time zone',
84
91
  'field.timeZoneHost': 'Host time zone',
85
92
  'field.command': 'Command',
@@ -137,6 +144,8 @@ window.__ModuleLoader__.load({
137
144
  'runs.loadError': 'Could not load runs.',
138
145
  'trigger.schedule': 'Scheduled',
139
146
  'trigger.manual': 'Run now',
147
+ 'trigger.event': 'Event',
148
+ 'run.events': '{count} event(s): {channels}',
140
149
  'run.exit': 'Exit code {code}',
141
150
  'run.duration': '{duration}',
142
151
  'run.openSession': 'Open woken session',
@@ -192,6 +201,7 @@ window.__ModuleLoader__.load({
192
201
  'detail.close': '关闭',
193
202
  'detail.nextRun': '下次运行 ',
194
203
  'detail.noNextRun': '没有待运行的计划',
204
+ 'detail.onEvents': '在 {channels} 有事件时运行',
195
205
  'detail.pause': '暂停计划',
196
206
  'detail.resume': '恢复计划',
197
207
  'detail.pauseUnavailable': '已在插件配置中关闭',
@@ -211,6 +221,12 @@ window.__ModuleLoader__.load({
211
221
  'notice.running': '自 {time} 起运行中({trigger})。',
212
222
  'notice.memory': 'DSH 存储不可用,运行记录只保存在内存中,重启后会丢失。',
213
223
  'field.schedule': '计划',
224
+ 'field.scheduleNone': '无:只在事件到来时运行',
225
+ 'field.on': '事件触发',
226
+ 'field.once': '只运行一次',
227
+ 'field.onceValue': '第一次非手动运行后结束',
228
+ 'field.pendingEvents': '等待中的事件',
229
+ 'field.pendingEventsValue': '{count} 个,{time} 运行',
214
230
  'field.timeZone': '时区',
215
231
  'field.timeZoneHost': '主机时区',
216
232
  'field.command': '命令',
@@ -268,6 +284,8 @@ window.__ModuleLoader__.load({
268
284
  'runs.loadError': '无法加载运行记录。',
269
285
  'trigger.schedule': '按计划',
270
286
  'trigger.manual': '立即运行',
287
+ 'trigger.event': '事件',
288
+ 'run.events': '{count} 个事件:{channels}',
271
289
  'run.exit': '退出码 {code}',
272
290
  'run.duration': '{duration}',
273
291
  'run.openSession': '打开唤醒的会话',
@@ -471,8 +489,11 @@ window.__ModuleLoader__.load({
471
489
  const OFF = new Set(['disabled', 'invalid', 'ended'])
472
490
 
473
491
  function scheduleText(job) {
474
- if (job.schedule?.kind === 'cron' || (!job.schedule && job.cron)) return job.timeZone ? `${job.cron} (${job.timeZone})` : job.cron
475
- return job.schedule?.text ?? ''
492
+ let text = ''
493
+ if (job.schedule?.kind === 'cron' || (!job.schedule && job.cron)) text = job.timeZone ? `${job.cron} (${job.timeZone})` : job.cron
494
+ else text = job.schedule?.text ?? ''
495
+ const on = job.on?.length ? `on ${job.on.join(', ')}` : ''
496
+ return [text, on].filter(Boolean).join(' · ')
476
497
  }
477
498
 
478
499
  function deliverText(target) {
@@ -576,8 +597,13 @@ window.__ModuleLoader__.load({
576
597
  const rows = [
577
598
  job.source === 'tool' && h(RuleRow, { key: 'source', label: t('field.source') }, t('field.sourceTool', { time: formatAbsolute(job.createdAt, t('time.locale')) })),
578
599
  job.createdBy && h(RuleRow, { key: 'createdBy', label: t('field.createdBy') }, h('button', { type: 'button', className: 'dcj-linkButton dcj-code', onClick: () => onOpenSession(job.createdBy) }, job.createdBy)),
579
- h(RuleRow, { key: 'schedule', label: t('field.schedule'), stack: job.schedule?.kind === 'rrule' }, h('span', { className: 'dcj-code' }, job.schedule?.kind === 'rrule' ? job.schedule.rrule : (job.schedule?.kind === 'at' ? job.schedule.at : job.cron))),
580
- h(RuleRow, { key: 'zone', label: t('field.timeZone') }, job.timeZone || t('field.timeZoneHost')),
600
+ h(RuleRow, { key: 'schedule', label: t('field.schedule'), stack: job.schedule?.kind === 'rrule' }, job.schedule || job.cron
601
+ ? h('span', { className: 'dcj-code' }, job.schedule?.kind === 'rrule' ? job.schedule.rrule : (job.schedule?.kind === 'at' ? job.schedule.at : job.cron))
602
+ : t('field.scheduleNone')),
603
+ (job.schedule || job.cron) && h(RuleRow, { key: 'zone', label: t('field.timeZone') }, job.timeZone || t('field.timeZoneHost')),
604
+ job.on?.length > 0 && h(RuleRow, { key: 'on', label: t('field.on') }, h('span', { className: 'dcj-code' }, job.on.join(', '))),
605
+ job.once && h(RuleRow, { key: 'once', label: t('field.once') }, t('field.onceValue')),
606
+ job.pendingEvents && h(RuleRow, { key: 'pending', label: t('field.pendingEvents') }, t('field.pendingEventsValue', { count: job.pendingEvents.count, time: formatAbsolute(job.pendingEvents.dueAt, t('time.locale')) })),
581
607
  h(RuleRow, { key: 'kind', label: t('field.kind') }, t(kindLabel)),
582
608
  job.command && h(RuleRow, { key: 'command', label: t('field.command'), stack: true }, h('pre', { className: 'dcj-pre' }, job.command)),
583
609
  job.command && h(RuleRow, { key: 'cwd', label: t('field.cwd') }, job.cwd ? h('span', { className: 'dcj-code' }, job.cwd) : t('field.cwdHost')),
@@ -614,6 +640,7 @@ window.__ModuleLoader__.load({
614
640
  const [open, setOpen] = useState(false)
615
641
  const bad = BAD.has(run.status)
616
642
  const meta = [t(`trigger.${run.trigger}`)]
643
+ if (run.events) meta.push(t('run.events', { count: run.events.count, channels: run.events.channels.join(', ') }))
617
644
  if (typeof run.durationMs === 'number') meta.push(formatDuration(run.durationMs, locale))
618
645
  if (typeof run.exitCode === 'number') meta.push(t('run.exit', { code: run.exitCode }))
619
646
  if (run.outcome && !/^exit \d+$/.test(run.outcome)) meta.push(run.outcome)
@@ -768,7 +795,7 @@ window.__ModuleLoader__.load({
768
795
  h('div', { className: 'dcj-detailHeader' }, h('h2', { className: 'dcj-readonlyName' }, name)),
769
796
  h('div', { className: 'dcj-nextRun' }, job.nextRunAt
770
797
  ? h('p', null, t('detail.nextRun'), h('time', { dateTime: job.nextRunAt }, formatAbsolute(job.nextRunAt, locale)), ' ', formatRelative(job.nextRunAt, locale, now))
771
- : h('p', null, t('detail.noNextRun'))),
798
+ : h('p', null, job.on?.length > 0 && job.state === 'active' ? t('detail.onEvents', { channels: job.on.join(', ') }) : t('detail.noNextRun'))),
772
799
  notices.map((text, i) => h('p', { key: i, className: 'dcj-detailNotice' }, text)),
773
800
  notice && h('p', { className: 'dcj-detailNotice', role: 'status' }, notice),
774
801
  failure && h('p', { className: 'dcj-failure', role: 'alert' }, failure),
package/index.js CHANGED
@@ -8,6 +8,9 @@
8
8
  * reads and controls jobs over authenticated routes on DSH's /api channel.
9
9
  * Results are delivered through whichever service a job's delivery target
10
10
  * names, looked up with `ctx.get()` when a result is ready (src/deliver.js).
11
+ * Events from the inbox directory (src/spool.js, bin/dsh-cron-event.js) and
12
+ * from supervised watchers (src/watchers.js) start the jobs subscribed to
13
+ * their channel (src/events.js).
11
14
  */
12
15
  import { Config } from './src/config.js'
13
16
  import { runCommand } from './src/command.js'
@@ -18,6 +21,11 @@ import { createAnswerChecks } from './src/answer-check.js'
18
21
  import { createRunLog } from './src/runlog.js'
19
22
  import { openHistory } from './src/history.js'
20
23
  import { createRoutes, createRpcHandler } from './src/rpc.js'
24
+ import { createEventSpool } from './src/spool.js'
25
+ import { defaultEventDir, defaultWatcherStateRoot } from './src/events.js'
26
+
27
+ /** Set once per DSH process, so `dsh.started` means a DSH start, not a plugin reload. */
28
+ const STARTED = Symbol.for('@soffits/dsh-cron-jobs/started')
21
29
 
22
30
  export const name = 'dsh-cron-jobs'
23
31
  export const inject = ['storageDomain']
@@ -25,7 +33,7 @@ export { Config }
25
33
 
26
34
  /**
27
35
  * @param {import('@deepseek-ai/cordis').Context} ctx
28
- * @param {{ jobs: import('./src/job.js').Job[], runLog?: string, historyRecords?: number, defaultAgentCwd?: string, autoArchive?: boolean, reuseWithinHours?: number, deliver?: { via?: string, to?: string } }} config
36
+ * @param {{ jobs: import('./src/job.js').Job[], watchers?: object[], events?: { coalesceSeconds?: number, maxRunsPerHour?: number }, runLog?: string, historyRecords?: number, defaultAgentCwd?: string, autoArchive?: boolean, reuseWithinHours?: number, deliver?: { via?: string, to?: string } }} config
29
37
  */
30
38
  export function apply(ctx, config) {
31
39
  const logger = ctx.logger('cron-jobs')
@@ -41,6 +49,7 @@ export function apply(ctx, config) {
41
49
  let jobs
42
50
  let history
43
51
  let checks
52
+ let spool
44
53
  // A job's answerCheck runs as the turn its prompt started is about to close.
45
54
  const stopTurnHook = ctx.on?.('agent/turn-stopping', payload => checks?.onTurnStopping(payload))
46
55
  const ready = (async () => {
@@ -71,16 +80,34 @@ export function apply(ctx, config) {
71
80
  signal: controller.signal,
72
81
  record,
73
82
  history,
83
+ events: config.events,
84
+ watchers: config.watchers ?? [],
85
+ watcherOptions: { stateRoot: defaultWatcherStateRoot() },
74
86
  }).start()
75
87
  current = jobs
88
+ // Once per process: jobs waiting for a DSH restart run now.
89
+ if (!globalThis[STARTED]) {
90
+ globalThis[STARTED] = true
91
+ jobs.emit({ channel: 'dsh.started', source: 'dsh', data: { processStartedAt: new Date(Date.now() - process.uptime() * 1000).toISOString() } })
92
+ }
93
+ if (controller.signal.aborted) return
94
+ spool = createEventSpool({
95
+ dir: defaultEventDir(),
96
+ handle: (input, ack) => jobs.emit(input, ack),
97
+ onError: error => logger.warn('event inbox: %s', error instanceof Error ? error.message : String(error)),
98
+ })
99
+ await spool.start()
76
100
  })().catch(error => logger.error('cron jobs not started: %s', error instanceof Error ? error.message : String(error)))
77
101
  return async () => {
78
102
  current = undefined
79
103
  stopTurnHook?.()
104
+ // Stop reading events first, so none reaches a stopping scheduler.
105
+ await spool?.stop()
80
106
  // Stop the timers first so no new run starts with an aborted signal.
81
107
  const stopping = jobs?.stop()
82
108
  controller.abort()
83
109
  await ready
110
+ await spool?.stop()
84
111
  // Let ended runs save their outcome before the storage closes.
85
112
  await (stopping ?? jobs?.stop())
86
113
  await history?.close()
package/package.json CHANGED
@@ -1,9 +1,12 @@
1
1
  {
2
2
  "name": "@soffits/dsh-cron-jobs",
3
- "version": "0.7.1",
3
+ "version": "0.9.0",
4
4
  "description": "Scheduled jobs for DeepSeek Harness: shell commands and agent prompts on cron, RRULE or one-time schedules, a gate that wakes an agent only when there is something to do, result delivery through any plugin that can send messages, tools to manage jobs from a conversation, and a Cron tasks page in the Web GUI.",
5
5
  "type": "module",
6
6
  "main": "./index.js",
7
+ "bin": {
8
+ "dsh-cron-event": "./bin/dsh-cron-event.js"
9
+ },
7
10
  "exports": {
8
11
  ".": "./index.js",
9
12
  "./tools": "./tools.js",
@@ -13,6 +16,7 @@
13
16
  "./package.json": "./package.json"
14
17
  },
15
18
  "files": [
19
+ "bin",
16
20
  "index.js",
17
21
  "tools.js",
18
22
  "client.js",
@@ -43,8 +47,8 @@
43
47
  "dsh": ">=0.2.2-rc.1 <0.3.0-0"
44
48
  },
45
49
  "scripts": {
46
- "test": "node --test \"test/*.test.js\"",
47
- "check": "for f in index.js tools.js client.js src/*.js test/*.js; do node --check \"$f\" || exit 1; done"
50
+ "test": "node --import ./test/home.js --test \"test/*.test.js\"",
51
+ "check": "for f in index.js tools.js client.js bin/*.js src/*.js test/*.js; do node --check \"$f\" || exit 1; done"
48
52
  },
49
53
  "dependencies": {
50
54
  "@deepseek-ai/dsh-util-time": "0.2.2-rc.1",
package/src/config.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import z from '@deepseek-ai/schemastery'
2
2
  import { DEFAULT_HISTORY_RECORDS } from './history.js'
3
+ import { DEFAULT_COALESCE_SECONDS, DEFAULT_MAX_RUNS_PER_HOUR } from './events.js'
3
4
 
4
5
  /** Default limit for one run of a job's command. */
5
6
  export const DEFAULT_TIMEOUT_SECONDS = 3600
@@ -29,10 +30,11 @@ const Agent = z.object({
29
30
 
30
31
  const Job = z.object({
31
32
  name: z.string().required().description('Job name, used in logs and session titles.'),
32
- cron: z.string().description('Cron expression (5 fields, or 6 with seconds first). Set exactly one of cron, rrule and at.'),
33
+ cron: z.string().description('Cron expression (5 fields, or 6 with seconds first). Set at most one of cron, rrule and at; a job with on needs none.'),
33
34
  rrule: z.string().role('textarea').description('RFC 5545 schedule: a DTSTART line and an RRULE line, such as "DTSTART;TZID=Europe/Berlin:20260901T080000" and "RRULE:FREQ=WEEKLY;BYDAY=MO". The zone comes from DTSTART.'),
34
35
  at: z.string().description('Run once at this time: ISO 8601 with an offset, or a local date-time read in timeZone.'),
35
36
  timeZone: z.string().description('IANA time zone for the cron expression or an at without offset, such as Europe/Berlin. The host zone when empty (an at without offset needs it).'),
37
+ on: z.array(z.string()).default([]).description('Event channels that start a run, such as mail.sakina or alerts.* (* matches any characters). Events arriving close together run the job once; the gate command gets them as JSON on stdin and the prompt gets them appended. Keep a slower schedule as a safety net.'),
36
38
  command: z.string().role('textarea').description('Shell command, run with bash (or sh when bash is missing). Leave empty for an agent-only job, which sends agent.prompt at every run.'),
37
39
  cwd: z.string().description('Working directory of the command. The host process directory when empty.'),
38
40
  timeoutSeconds: z.natural().default(DEFAULT_TIMEOUT_SECONDS)
@@ -42,8 +44,23 @@ const Job = z.object({
42
44
  agent: Agent,
43
45
  })
44
46
 
47
+ const Watcher = z.object({
48
+ id: z.string().required().description('Watcher id (letters, digits, _ . -), shown in logs and alerts.'),
49
+ channel: z.string().required().description('Channel each output line is emitted on, such as mail.sakina.'),
50
+ command: z.string().role('textarea').required().description('Long-running shell command, run with bash. Each stdout line is an event: a JSON object line is its data, any other line its text; {"wakeAgent": false} lines are ignored. It is restarted with backoff when it exits.'),
51
+ cwd: z.string().description('Working directory. The host process directory when empty.'),
52
+ enabled: z.boolean().default(true).description('Run this watcher.'),
53
+ })
54
+
55
+ const Events = z.object({
56
+ coalesceSeconds: z.natural().default(DEFAULT_COALESCE_SECONDS).description('Events for one job that arrive within this many seconds of the first one start a single run.'),
57
+ maxRunsPerHour: z.natural().default(DEFAULT_MAX_RUNS_PER_HOUR).description('Most event-started runs of one job in any hour; past that, events wait and run together. 0 means no cap.'),
58
+ })
59
+
45
60
  export const Config = z.object({
46
61
  jobs: z.array(Job).default([]).description('Scheduled jobs.'),
62
+ watchers: z.array(Watcher).default([]).description('Long-running commands whose output lines are events (see a job\'s on). Watchers can also be added from a conversation with the watch tool.'),
63
+ events: Events.description('How events are batched into runs.'),
47
64
  defaultAgentCwd: z.string().description('Working directory of woken sessions for jobs whose agent.cwd is empty. Sessions are only found by session search from the same directory, so this is usually the main workspace.'),
48
65
  autoArchive: z.boolean().default(true).description('Archive woken sessions once their turn ends, for jobs that do not set agent.autoArchive. Archived sessions leave the sidebar\'s active list but stay in DSH and in session search.'),
49
66
  reuseWithinHours: z.number().min(0).default(0).description('Reuse window for jobs that do not set agent.reuseWithinHours: send the prompt into the job\'s previous woken session when it was opened within this many hours. 0 always opens a new session.'),