@soffits/dsh-cron-jobs 0.7.1 → 0.8.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 +74 -7
- package/bin/dsh-cron-event.js +101 -0
- package/client.js +32 -5
- package/index.js +28 -1
- package/package.json +7 -3
- package/src/config.js +18 -1
- package/src/controller.js +266 -20
- package/src/events.js +302 -0
- package/src/history.js +11 -8
- package/src/job.js +14 -8
- package/src/prompt.js +26 -7
- package/src/spool.js +176 -0
- package/src/store.js +17 -1
- package/src/watchers.js +374 -0
- package/tools.js +59 -4
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.
|
|
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
|
|
|
@@ -211,16 +215,79 @@ and point a job at it with `deliver: { via: myChannel, to: <address> }`.
|
|
|
211
215
|
|
|
212
216
|
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
217
|
|
|
218
|
+
## Events
|
|
219
|
+
|
|
220
|
+
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:
|
|
221
|
+
|
|
222
|
+
```yaml
|
|
223
|
+
- name: Mailbox
|
|
224
|
+
on: [mail.me]
|
|
225
|
+
cron: '0 */2 * * *' # slow safety net in case an event is missed
|
|
226
|
+
command: ./mail-gate.sh
|
|
227
|
+
agent:
|
|
228
|
+
prompt: Handle the new mail.
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
**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`.
|
|
232
|
+
|
|
233
|
+
**Emitting an event.** The package installs a small CLI:
|
|
234
|
+
|
|
235
|
+
```sh
|
|
236
|
+
dsh-cron-event ci.run.123 --data '{"conclusion": "success"}'
|
|
237
|
+
gh run watch 123 --exit-status; dsh-cron-event ci.run.123 --data "{\"exit\": $?}"
|
|
238
|
+
echo '{"subject": "hi"}' | dsh-cron-event mail.me --data -
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
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.
|
|
242
|
+
|
|
243
|
+
**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:
|
|
244
|
+
|
|
245
|
+
- 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.
|
|
246
|
+
- 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.
|
|
247
|
+
|
|
248
|
+
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.
|
|
249
|
+
|
|
250
|
+
**`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.
|
|
251
|
+
|
|
252
|
+
**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.
|
|
253
|
+
|
|
254
|
+
**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.
|
|
255
|
+
|
|
256
|
+
### Watchers
|
|
257
|
+
|
|
258
|
+
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:
|
|
259
|
+
|
|
260
|
+
- a JSON object line is the event's data, and its string `id` field, if any, is the dedupe key;
|
|
261
|
+
- any other non-empty line is the event's text;
|
|
262
|
+
- `{"wakeAgent": false}` lines are ignored.
|
|
263
|
+
|
|
264
|
+
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.
|
|
265
|
+
|
|
266
|
+
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:
|
|
267
|
+
|
|
268
|
+
```
|
|
269
|
+
cron_job_watch create id=ci-123 channel=ci.123 once=true
|
|
270
|
+
command='gh run watch 123 --exit-status >/dev/null; echo "{\"exit\": $?}"'
|
|
271
|
+
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."
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
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:
|
|
275
|
+
|
|
276
|
+
- **JMAP mail** (RFC 8620 EventSource, served by Stalwart, Fastmail and others): stream `eventSourceUrl` with `types=EmailDelivery` and print a line per `state` push.
|
|
277
|
+
- **IMAP IDLE**: [goimapnotify](https://gitlab.com/shackra/goimapnotify) with `onNewMail: echo new`.
|
|
278
|
+
- **ntfy**: `curl -sN 'https://ntfy.sh/<topic>,<topic>/json?since=<last id>'`, printing the `message` events.
|
|
279
|
+
|
|
214
280
|
## Jobs created from a conversation
|
|
215
281
|
|
|
216
|
-
The `cron-jobs-tools` row registers
|
|
282
|
+
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
283
|
|
|
218
284
|
| Tool | What it does |
|
|
219
285
|
|---|---|
|
|
220
|
-
| `cron_job_create` | Create a job: a title, a prompt and/or a command,
|
|
221
|
-
| `cron_job_edit` | `update` the given fields, `pause`, `resume` (continues from now), or `delete` a job by id. |
|
|
286
|
+
| `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. |
|
|
287
|
+
| `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
288
|
| `cron_job_list` | Every job, from the config and from tools, with its id, state, schedule, next run, target and last run. |
|
|
223
289
|
| `cron_job_view` | One job's full definition and its five latest runs. |
|
|
290
|
+
| `cron_job_watch` | `create`, `delete` or `list` [watchers](#watchers). |
|
|
224
291
|
|
|
225
292
|
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
293
|
|
|
@@ -247,7 +314,7 @@ A delegated subagent can use the tools, but its own session cannot be a target,
|
|
|
247
314
|
The Web GUI gets a **Cron tasks** entry in the sidebar, laid out like DSH's own Automation tasks page:
|
|
248
315
|
|
|
249
316
|
- 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
|
|
317
|
+
- 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
318
|
- 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
319
|
|
|
253
320
|
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
|
-
|
|
475
|
-
|
|
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' },
|
|
580
|
-
|
|
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.
|
|
3
|
+
"version": "0.8.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
|
|
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.'),
|