@soffits/dsh-cron-jobs 0.8.0 → 0.10.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 +18 -1
- package/bin/dsh-cron-event.js +1 -1
- package/package.json +1 -1
- package/src/answer-check.js +5 -5
- package/src/config.js +2 -2
- package/src/controller.js +76 -3
- package/src/deliver.js +15 -3
- package/src/events.js +1 -1
- package/src/history.js +19 -2
- package/src/job.js +230 -83
- package/src/prompt.js +32 -5
- package/src/session.js +16 -9
- package/tools.js +2 -2
package/README.md
CHANGED
|
@@ -92,7 +92,7 @@ Config jobs live in the config of the `cron-jobs` row. Add an override to your p
|
|
|
92
92
|
|---|---|
|
|
93
93
|
| `name` | Job name, used in logs and session titles. Must be unique. |
|
|
94
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.
|
|
95
|
+
| `on` | Event channel patterns that start a run, such as `[mail.inbox, alerts.*]`. See [Events](#events). |
|
|
96
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). |
|
|
97
97
|
| `at` | Run once at this time: ISO 8601 with an offset, or a local date-time read in `timeZone`. |
|
|
98
98
|
| `timeZone` | IANA time zone for the cron expression or an `at` without offset. The Host's zone when empty. |
|
|
@@ -167,6 +167,12 @@ Where results go is decided per job: its own `deliver` (or `false`), otherwise n
|
|
|
167
167
|
|
|
168
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.
|
|
169
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
|
+
|
|
170
176
|
### Answer checks
|
|
171
177
|
|
|
172
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.
|
|
@@ -175,6 +181,16 @@ Use it for checks that are cheap to script and costly to miss, such as the answe
|
|
|
175
181
|
|
|
176
182
|
It works on DSH's `agent/turn-stopping` hook: a listener that steers a message there makes the agent loop run one more step in the same turn.
|
|
177
183
|
|
|
184
|
+
### Who sent a prompt
|
|
185
|
+
|
|
186
|
+
Every prompt a job puts into a session has the source kind `schedule`, which the Web GUI shows as a scheduled run, and names the job as `principal`, the field DSH uses for the caller behind a user message:
|
|
187
|
+
|
|
188
|
+
```js
|
|
189
|
+
{ kind: 'cron-job', channel: 'cron', id, name, trigger, events }
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`id` is the job's id (its name for a config job), `name` its name, `trigger` what started the run (`schedule`, `manual`, `event`, `rerun`, or `answer-check` for an answer check's rewrite request), and `events` the channels of the events that started an event run. Scripts that read session logs can tell job prompts apart, and which job sent each, without parsing the text.
|
|
193
|
+
|
|
178
194
|
### Delivery channels
|
|
179
195
|
|
|
180
196
|
A delivery target is `{ via, to }`: `via` names a DSH service, `to` is an address that service understands (a chat topic, a mailbox, a webhook name; it can be empty). When a result is ready, the plugin looks the service up by name with `ctx.get(via)` and calls:
|
|
@@ -186,6 +202,7 @@ await service.send({
|
|
|
186
202
|
files, // string[]: absolute file paths
|
|
187
203
|
from: {
|
|
188
204
|
job, // string: the job's name
|
|
205
|
+
jobId, // string: the job's id (its name for a config job)
|
|
189
206
|
sessionId, // string, agent and gated jobs only: the session that wrote the answer
|
|
190
207
|
},
|
|
191
208
|
})
|
package/bin/dsh-cron-event.js
CHANGED
|
@@ -13,7 +13,7 @@ import { enqueueEvent, waitForEventResult } from '../src/spool.js'
|
|
|
13
13
|
const usage = `Usage: dsh-cron-event <channel> [--data <json> | --data - | --text <text>]
|
|
14
14
|
[--id <dedupe key>] [--source <label>] [--no-wait] [--timeout <seconds>]
|
|
15
15
|
|
|
16
|
-
Emits one event on <channel> (dot-separated names, such as mail.
|
|
16
|
+
Emits one event on <channel> (dot-separated names, such as mail.inbox or
|
|
17
17
|
ci.run.123). Jobs whose on patterns match it run once the events around it are
|
|
18
18
|
gathered (about 30 s). The event is a hint: jobs check the source themselves.
|
|
19
19
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@soffits/dsh-cron-jobs",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.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",
|
package/src/answer-check.js
CHANGED
|
@@ -67,7 +67,7 @@ export function checkable(text) {
|
|
|
67
67
|
* @param {() => Date} [deps.now]
|
|
68
68
|
*/
|
|
69
69
|
export function createAnswerChecks({ run, logger, record = async () => {}, now = () => new Date() }) {
|
|
70
|
-
/** @type {Map<string, { job: string, command: string, cwd?: string, at: number, steered: boolean, verdict?: string }>} */
|
|
70
|
+
/** @type {Map<string, { job: string, jobId?: string, command: string, cwd?: string, at: number, steered: boolean, verdict?: string }>} */
|
|
71
71
|
const pending = new Map()
|
|
72
72
|
|
|
73
73
|
async function check(entry, text, signal) {
|
|
@@ -80,12 +80,12 @@ export function createAnswerChecks({ run, logger, record = async () => {}, now =
|
|
|
80
80
|
/**
|
|
81
81
|
* Check the answer to this prompt before its turn closes.
|
|
82
82
|
* @param {string} messageId
|
|
83
|
-
* @param {{ job: string, command: string, cwd?: string }} options
|
|
83
|
+
* @param {{ job: string, jobId?: string, command: string, cwd?: string }} options
|
|
84
84
|
*/
|
|
85
|
-
expect(messageId, { job, command, cwd }) {
|
|
85
|
+
expect(messageId, { job, jobId, command, cwd }) {
|
|
86
86
|
const at = now().getTime()
|
|
87
87
|
for (const [id, entry] of pending) if (at - entry.at > ANSWER_CHECK_TTL_MS) pending.delete(id)
|
|
88
|
-
pending.set(messageId, { job, command, ...(cwd ? { cwd } : {}), at, steered: false })
|
|
88
|
+
pending.set(messageId, { job, ...(jobId ? { jobId } : {}), command, ...(cwd ? { cwd } : {}), at, steered: false })
|
|
89
89
|
},
|
|
90
90
|
|
|
91
91
|
/** Stop watching a prompt; returns what its check did ('steered', 'passed', 'error' or undefined). */
|
|
@@ -130,7 +130,7 @@ export function createAnswerChecks({ run, logger, record = async () => {}, now =
|
|
|
130
130
|
entry.verdict = 'steered'
|
|
131
131
|
logger.info('[%s] answer check asked for a rewrite', entry.job)
|
|
132
132
|
await record({ ...line, status: 'steered', request: outcome.request })
|
|
133
|
-
agent.steer(userMessage(outcome.request, randomUUID()))
|
|
133
|
+
agent.steer(userMessage(outcome.request, randomUUID(), { kind: 'cron-job', channel: 'cron', id: entry.jobId ?? entry.job, name: entry.job, trigger: 'answer-check' }))
|
|
134
134
|
}
|
|
135
135
|
return
|
|
136
136
|
}
|
package/src/config.js
CHANGED
|
@@ -34,7 +34,7 @@ const Job = z.object({
|
|
|
34
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.'),
|
|
35
35
|
at: z.string().description('Run once at this time: ISO 8601 with an offset, or a local date-time read in timeZone.'),
|
|
36
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.
|
|
37
|
+
on: z.array(z.string()).default([]).description('Event channels that start a run, such as mail.inbox 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.'),
|
|
38
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.'),
|
|
39
39
|
cwd: z.string().description('Working directory of the command. The host process directory when empty.'),
|
|
40
40
|
timeoutSeconds: z.natural().default(DEFAULT_TIMEOUT_SECONDS)
|
|
@@ -46,7 +46,7 @@ const Job = z.object({
|
|
|
46
46
|
|
|
47
47
|
const Watcher = z.object({
|
|
48
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.
|
|
49
|
+
channel: z.string().required().description('Channel each output line is emitted on, such as mail.inbox.'),
|
|
50
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
51
|
cwd: z.string().description('Working directory. The host process directory when empty.'),
|
|
52
52
|
enabled: z.boolean().default(true).description('Run this watcher.'),
|
package/src/controller.js
CHANGED
|
@@ -11,6 +11,15 @@ export const WATCHDOG_MS = 60_000
|
|
|
11
11
|
/** How late a tick must be before the watchdog treats its timer as lost. */
|
|
12
12
|
export const OVERDUE_MS = 60_000
|
|
13
13
|
|
|
14
|
+
/** Wait after a cut-off turn is found before it runs again, so DSH has finished starting (or stopping). */
|
|
15
|
+
export const RERUN_DELAY_MS = 30_000
|
|
16
|
+
|
|
17
|
+
/** A cut-off run older than this is not rerun: its moment has passed. */
|
|
18
|
+
export const RERUN_MAX_AGE_MS = 2 * 3600_000
|
|
19
|
+
|
|
20
|
+
/** A cut-off run is not rerun when the job's next scheduled run is this close. */
|
|
21
|
+
export const RERUN_MIN_LEAD_MS = 15 * 60_000
|
|
22
|
+
|
|
14
23
|
/** Longest job title accepted from the tools. */
|
|
15
24
|
export const MAX_TITLE_LENGTH = 200
|
|
16
25
|
|
|
@@ -77,8 +86,9 @@ export class CronJobs {
|
|
|
77
86
|
* @param {{ set: typeof setTimeout, clear: typeof clearTimeout }} [options.timers] - Event batch timers; replaceable for tests.
|
|
78
87
|
* @param {object[]} [options.watchers] - Watchers from the plugin config.
|
|
79
88
|
* @param {object} [options.watcherOptions] - Passed to {@link WatcherSupervisor} (stateRoot, limits, spawn).
|
|
89
|
+
* @param {{ delayMs?: number, maxAgeMs?: number, minLeadMs?: number }} [options.rerun] - Limits for rerunning cut-off runs (see planRerun).
|
|
80
90
|
*/
|
|
81
|
-
constructor({ jobs, logger, run, wake, reuse, settle, send, answer, checks, defaults = {}, signal, record, history, CronClass = CronTimer, TimerClass = ScheduleTimer, now = () => new Date(), watchdogMs = WATCHDOG_MS, overdueMs = OVERDUE_MS, events = {}, timers, watchers = [], watcherOptions = {} }) {
|
|
91
|
+
constructor({ jobs, logger, run, wake, reuse, settle, send, answer, checks, defaults = {}, signal, record, history, CronClass = CronTimer, TimerClass = ScheduleTimer, now = () => new Date(), watchdogMs = WATCHDOG_MS, overdueMs = OVERDUE_MS, events = {}, timers, watchers = [], watcherOptions = {}, rerun = {} }) {
|
|
82
92
|
this.logger = logger
|
|
83
93
|
this.defaults = defaults
|
|
84
94
|
this.history = history
|
|
@@ -95,6 +105,13 @@ export class CronJobs {
|
|
|
95
105
|
maxRunsPerHour: events.maxRunsPerHour ?? DEFAULT_MAX_RUNS_PER_HOUR,
|
|
96
106
|
...(timers ? { timers } : {}),
|
|
97
107
|
}
|
|
108
|
+
this.rerunLimits = {
|
|
109
|
+
delayMs: rerun.delayMs ?? RERUN_DELAY_MS,
|
|
110
|
+
maxAgeMs: rerun.maxAgeMs ?? RERUN_MAX_AGE_MS,
|
|
111
|
+
minLeadMs: rerun.minLeadMs ?? RERUN_MIN_LEAD_MS,
|
|
112
|
+
}
|
|
113
|
+
/** Reruns waiting for their delay. */
|
|
114
|
+
this.rerunTimers = new Set()
|
|
98
115
|
this.deduper = new Deduper({ now: () => this.now().getTime() })
|
|
99
116
|
this.configWatchers = []
|
|
100
117
|
for (const def of watchers) {
|
|
@@ -134,6 +151,7 @@ export class CronJobs {
|
|
|
134
151
|
entry.runner = new JobRunner(entry.job, {
|
|
135
152
|
...this.deps,
|
|
136
153
|
...(entry.record ? { keepSession: sessionId => this.keepSession(entry, sessionId) } : {}),
|
|
154
|
+
onCutOff: runId => this.planRerun(entry, runId),
|
|
137
155
|
})
|
|
138
156
|
this.entries.set(entry.job.id, entry)
|
|
139
157
|
this.subscribe(entry)
|
|
@@ -202,8 +220,8 @@ export class CronJobs {
|
|
|
202
220
|
for (const entry of this.entries.values()) {
|
|
203
221
|
// Archives an earlier copy of the plugin left waiting on a running turn.
|
|
204
222
|
entry.runner.resumeArchives().catch(error => this.logger.warn('[%s] pending archives not resumed: %s', entry.job.name, String(error)))
|
|
205
|
-
//
|
|
206
|
-
entry.runner.
|
|
223
|
+
// Turns, answers and reruns an earlier copy was still waiting for.
|
|
224
|
+
entry.runner.resumeRuns().catch(error => this.logger.warn('[%s] pending runs not resumed: %s', entry.job.name, String(error)))
|
|
207
225
|
}
|
|
208
226
|
for (const entry of this.entries.values()) this.arm(entry)
|
|
209
227
|
// A line per start and stop, so a gap in the run log can be told apart
|
|
@@ -408,6 +426,55 @@ export class CronJobs {
|
|
|
408
426
|
}
|
|
409
427
|
}
|
|
410
428
|
|
|
429
|
+
/**
|
|
430
|
+
* A run's turn was cut off by DSH (a restart or reload disposed it): rerun
|
|
431
|
+
* it once, after a short delay so a stopping DSH does not start it and a
|
|
432
|
+
* starting one has settled. A stop cancels the wait and the rerun stays
|
|
433
|
+
* pending in the run's history for the next start.
|
|
434
|
+
*/
|
|
435
|
+
planRerun(entry, runId) {
|
|
436
|
+
if (this.stopped) return
|
|
437
|
+
const timer = setTimeout(() => {
|
|
438
|
+
this.rerunTimers.delete(timer)
|
|
439
|
+
this.rerun(entry, runId).catch(error => this.logger.warn('[%s] rerun not started: %s', entry.job.name, String(error)))
|
|
440
|
+
}, this.rerunLimits.delayMs)
|
|
441
|
+
timer.unref?.()
|
|
442
|
+
this.rerunTimers.add(timer)
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
/** Start a pending rerun, or record why it is skipped. */
|
|
446
|
+
async rerun(entry, runId) {
|
|
447
|
+
if (this.stopped || this.entries.get(entry.job.id) !== entry || this.history === undefined) return
|
|
448
|
+
const runs = this.history.runs(entry.job.id)
|
|
449
|
+
const run = runs.find(saved => saved.id === runId)
|
|
450
|
+
if (run?.rerun?.status !== 'pending') return
|
|
451
|
+
const note = this.rerunSkipReason(entry, run, runs)
|
|
452
|
+
if (note !== undefined) {
|
|
453
|
+
const time = this.now().toISOString()
|
|
454
|
+
await this.history.update(entry.job.id, runId, { rerun: { status: 'skipped', at: time, note } })
|
|
455
|
+
await this.record({ time, job: entry.job.name, event: 'rerun-skipped', runId, note })
|
|
456
|
+
this.logger.info('[%s] cut-off run not rerun: %s', entry.job.name, note)
|
|
457
|
+
return
|
|
458
|
+
}
|
|
459
|
+
// Not a scheduled run: it neither moves the schedule nor ends a once job.
|
|
460
|
+
this.runTracked(entry, entry.runner.tick({ trigger: run.trigger, rerunOf: run }))
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
/** Why a cut-off run should not run again now, or undefined. */
|
|
464
|
+
rerunSkipReason(entry, run, runs) {
|
|
465
|
+
const now = this.now().getTime()
|
|
466
|
+
if (!run.sessionId) return 'the run has no session'
|
|
467
|
+
if (now - Date.parse(run.startedAt) > this.rerunLimits.maxAgeMs) return `it started more than ${minutes(this.rerunLimits.maxAgeMs)} ago`
|
|
468
|
+
if (entry.runner.running) return 'another run of the job is in progress'
|
|
469
|
+
const newer = runs.slice(0, runs.indexOf(run))
|
|
470
|
+
if (newer.some(later => later.status === 'woke' || later.status === 'running')) return 'a later run has woken the agent since'
|
|
471
|
+
if (!entry.record && entry.job.enabled === false) return 'the job is disabled'
|
|
472
|
+
if (this.pausedEntry(entry)) return 'the job is paused'
|
|
473
|
+
const next = this.nextRun(entry)
|
|
474
|
+
if (next !== null && next.getTime() - now < this.rerunLimits.minLeadMs) return `the next run is due at ${next.toISOString()}`
|
|
475
|
+
return undefined
|
|
476
|
+
}
|
|
477
|
+
|
|
411
478
|
/** A new_once job opened its session: later runs go there. */
|
|
412
479
|
async keepSession(entry, sessionId) {
|
|
413
480
|
const current = this.store?.get(entry.job.id)
|
|
@@ -438,6 +505,8 @@ export class CronJobs {
|
|
|
438
505
|
if (this.stopped) return Promise.allSettled([...this.inflight])
|
|
439
506
|
this.stopped = true
|
|
440
507
|
clearInterval(this.watchdog)
|
|
508
|
+
for (const timer of this.rerunTimers) clearTimeout(timer)
|
|
509
|
+
this.rerunTimers.clear()
|
|
441
510
|
for (const entry of this.entries.values()) {
|
|
442
511
|
entry.timer?.stop()
|
|
443
512
|
entry.batcher?.stop()
|
|
@@ -717,6 +786,10 @@ export class CronJobs {
|
|
|
717
786
|
}
|
|
718
787
|
}
|
|
719
788
|
|
|
789
|
+
function minutes(ms) {
|
|
790
|
+
return ms % 3600_000 === 0 ? `${ms / 3600_000} h` : `${Math.round(ms / 60_000)} min`
|
|
791
|
+
}
|
|
792
|
+
|
|
720
793
|
/** A config job as the runner and timers see it. */
|
|
721
794
|
function fromConfig(job) {
|
|
722
795
|
const given = ['cron', 'rrule', 'at'].filter(key => typeof job[key] === 'string' && job[key].trim() !== '')
|
package/src/deliver.js
CHANGED
|
@@ -134,10 +134,11 @@ export function failureLine(job, result) {
|
|
|
134
134
|
* (Claude Code through dsh-oh-my-claude) put every text block of their own
|
|
135
135
|
* inner tool loop into one assistant message, so narration would otherwise
|
|
136
136
|
* be glued in front of a final `[SILENT]`. `done` is false while the turn is
|
|
137
|
-
* still open, or the message has not entered a turn yet.
|
|
137
|
+
* still open, or the message has not entered a turn yet. `cause` says why an
|
|
138
|
+
* aborted turn stopped (`user`, `parent`, `disposed`, `hook`).
|
|
138
139
|
* @param {Array<{ type: string, data?: any }>} log - The session's event log.
|
|
139
140
|
* @param {string} messageId - Id of the prompt the job sent.
|
|
140
|
-
* @returns {{ done: boolean, text?: string, reason?: string }}
|
|
141
|
+
* @returns {{ done: boolean, text?: string, reason?: string, cause?: string }}
|
|
141
142
|
*/
|
|
142
143
|
export function finalAnswer(log, messageId) {
|
|
143
144
|
const start = log.findIndex(event => event.type === 'user/message' && event.data?.id === messageId)
|
|
@@ -154,12 +155,23 @@ export function finalAnswer(log, messageId) {
|
|
|
154
155
|
// dsh-fallback-models stops a turn whose model failed and continues the
|
|
155
156
|
// work in the next turn on a fallback model; the answer is there.
|
|
156
157
|
if (continuedElsewhere(event.data?.reason)) continue
|
|
157
|
-
|
|
158
|
+
const cause = event.data?.reason?.reason?.kind
|
|
159
|
+
return { done: true, text, reason: event.data?.reason?.kind, ...(typeof cause === 'string' ? { cause } : {}) }
|
|
158
160
|
}
|
|
159
161
|
}
|
|
160
162
|
return { done: false }
|
|
161
163
|
}
|
|
162
164
|
|
|
165
|
+
/**
|
|
166
|
+
* Whether a turn was cut off from outside rather than finished: DSH disposed
|
|
167
|
+
* its agent (a restart, or a profile reload that replaced the agent) before
|
|
168
|
+
* the turn ended. A turn a person stopped, or one that failed, is not.
|
|
169
|
+
* @param {{ reason?: string, cause?: string }} answer
|
|
170
|
+
*/
|
|
171
|
+
export function cutOff(answer) {
|
|
172
|
+
return answer.reason === 'aborted' && answer.cause === 'disposed'
|
|
173
|
+
}
|
|
174
|
+
|
|
163
175
|
/** Prefix of the stop reason dsh-fallback-models records on a turn it continues. */
|
|
164
176
|
export const FALLBACK_REASON_PREFIX = 'dsh-fallback-models:'
|
|
165
177
|
|
package/src/events.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* job reads the truth from its source, so a lost or forged event costs at
|
|
5
5
|
* most one missed or wasted run (the job's schedule is the safety net).
|
|
6
6
|
*
|
|
7
|
-
* - Channels are dot-separated names such as `mail.
|
|
7
|
+
* - Channels are dot-separated names such as `mail.inbox` or `dsh.started`.
|
|
8
8
|
* - A job's `on` lists channel patterns; `*` matches one or more characters
|
|
9
9
|
* of any kind, dots included (`mail.*` matches `mail.icloud.inbox`).
|
|
10
10
|
* - An event may carry a dedupe key: a second event with the same channel and
|
package/src/history.js
CHANGED
|
@@ -32,6 +32,23 @@ const runSchema = z.object({
|
|
|
32
32
|
reuseNote: z.string().optional(),
|
|
33
33
|
// The prompt went to the job's target session (an existing session, or the one a new_once job opened).
|
|
34
34
|
targeted: z.boolean().optional(),
|
|
35
|
+
// The turn the woken prompt started: pending until it ends, then ended, or
|
|
36
|
+
// cut-off when DSH disposed it (a restart or reload) before it finished.
|
|
37
|
+
turn: z.object({
|
|
38
|
+
status: z.enum(['pending', 'ended', 'cut-off']),
|
|
39
|
+
messageId: z.string(),
|
|
40
|
+
reason: z.string().optional(),
|
|
41
|
+
}).optional(),
|
|
42
|
+
// A cut-off run's one rerun: pending until DSH is back, then started (see
|
|
43
|
+
// runId) or skipped (see note).
|
|
44
|
+
rerun: z.object({
|
|
45
|
+
status: z.enum(['pending', 'started', 'skipped']),
|
|
46
|
+
at: z.string().optional(),
|
|
47
|
+
runId: z.string().optional(),
|
|
48
|
+
note: z.string().optional(),
|
|
49
|
+
}).optional(),
|
|
50
|
+
// This run reruns the cut-off run with this id.
|
|
51
|
+
rerunOf: z.string().optional(),
|
|
35
52
|
// Auto-archive of the woken session: pending until its turn ends, then
|
|
36
53
|
// archived, kept (see archiveNote), or superseded (a later run reused it).
|
|
37
54
|
archive: z.enum(['pending', 'archived', 'kept', 'superseded']).optional(),
|
|
@@ -136,11 +153,11 @@ export class HistoryStore {
|
|
|
136
153
|
* Save a started run and drop the oldest ones beyond the limit.
|
|
137
154
|
* @returns {Promise<string>} The run id.
|
|
138
155
|
*/
|
|
139
|
-
async begin(name, { trigger, startedAt, events }) {
|
|
156
|
+
async begin(name, { trigger, startedAt, events, rerunOf }) {
|
|
140
157
|
const id = randomUUID()
|
|
141
158
|
await this.change(name, state => ({
|
|
142
159
|
...state,
|
|
143
|
-
runs: [...state.runs, { id, trigger, startedAt, status: 'running', ...(events ? { events } : {}) }].slice(-this.limit),
|
|
160
|
+
runs: [...state.runs, { id, trigger, startedAt, status: 'running', ...(events ? { events } : {}), ...(rerunOf ? { rerunOf } : {}) }].slice(-this.limit),
|
|
144
161
|
}))
|
|
145
162
|
return id
|
|
146
163
|
}
|
package/src/job.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { randomUUID } from 'node:crypto'
|
|
2
2
|
import { decideWake } from './wake.js'
|
|
3
|
-
import { commandResultText, describeTarget, messageFromText, resolveDelivery } from './deliver.js'
|
|
4
|
-
import { buildAgentPrompt, formatLocalTime, sessionTitle } from './prompt.js'
|
|
3
|
+
import { commandResultText, cutOff, describeTarget, messageFromText, resolveDelivery } from './deliver.js'
|
|
4
|
+
import { buildAgentPrompt, buildRerunPrompt, formatLocalTime, sessionTitle } from './prompt.js'
|
|
5
5
|
import { HISTORY_TAIL_CHARS } from './history.js'
|
|
6
6
|
import { batchSummary, eventInput } from './events.js'
|
|
7
7
|
|
|
@@ -106,6 +106,7 @@ export class JobRunner {
|
|
|
106
106
|
* @param {(target: { via: string, to: string }, message: { text: string, files: string[] }, from: { job: string, sessionId?: string }, options: { waitMs?: number, onWait?: Function }) => Promise<{ status: 'sent' | 'failed' | 'unavailable' | 'stopped', attempts: number, error?: string }>} [deps.send] - Hands a result to its delivery service (see deliver.js sendMessage); without it nothing is delivered.
|
|
107
107
|
* @param {(sessionId: string, messageId: string, options: { signal?: AbortSignal }) => Promise<{ pending: true } | { text: string, reason?: string } | { error: string }>} [deps.answer] - Waits for the final answer to a prompt (see session.js waitForAnswer).
|
|
108
108
|
* @param {ReturnType<typeof import('./answer-check.js').createAnswerChecks>} [deps.checks] - Answer checks (see answer-check.js); without it a job's answerCheck is ignored.
|
|
109
|
+
* @param {(runId: string) => void} [deps.onCutOff] - Told about a run whose turn DSH cut off and that waits for its rerun (see CronJobs.planRerun); without it the rerun stays pending.
|
|
109
110
|
* @param {{ agentCwd?: string, autoArchive?: boolean, reuseWithinHours?: number, deliver?: object }} [deps.defaults] - Plugin-level agent settings and the default delivery target.
|
|
110
111
|
* @param {{ info: Function, warn: Function }} deps.logger
|
|
111
112
|
* @param {AbortSignal} [deps.signal] - Stops a running command when aborted.
|
|
@@ -113,11 +114,12 @@ export class JobRunner {
|
|
|
113
114
|
* @param {{ begin: Function, finish: Function }} [deps.history] - Saved run history (see history.js).
|
|
114
115
|
* @param {() => Date} [deps.now]
|
|
115
116
|
*/
|
|
116
|
-
constructor(job, { run, wake, reuse, keepSession, settle, send, answer, checks, defaults = {}, logger, signal, record = async () => {}, history = NO_HISTORY, now = () => new Date() }) {
|
|
117
|
+
constructor(job, { run, wake, reuse, keepSession, settle, send, answer, checks, onCutOff, defaults = {}, logger, signal, record = async () => {}, history = NO_HISTORY, now = () => new Date() }) {
|
|
117
118
|
this.job = job
|
|
118
119
|
this.send = send
|
|
119
120
|
this.answer = answer
|
|
120
121
|
this.checks = checks
|
|
122
|
+
this.onCutOff = onCutOff
|
|
121
123
|
this.reuse = reuse
|
|
122
124
|
this.keepSession = keepSession
|
|
123
125
|
this.settle = settle
|
|
@@ -143,10 +145,10 @@ export class JobRunner {
|
|
|
143
145
|
/**
|
|
144
146
|
* Run the job once. `running` and `current` are set before the first await,
|
|
145
147
|
* so a caller can read them as soon as this returns its promise.
|
|
146
|
-
* @param {{ trigger?: 'schedule' | 'manual' | 'event', events?: { events: object[], dropped: number } }} [options] - What started the run; an event run carries its batch of events.
|
|
148
|
+
* @param {{ trigger?: 'schedule' | 'manual' | 'event', events?: { events: object[], dropped: number }, rerunOf?: object }} [options] - What started the run; an event run carries its batch of events; a rerun carries the saved run it reruns (see continueRun).
|
|
147
149
|
* @returns {Promise<{ status: 'skipped' | 'done' | 'failed' | 'idle' | 'woke' | 'wake-failed', sessionId?: string }>}
|
|
148
150
|
*/
|
|
149
|
-
async tick({ trigger = 'schedule', events } = {}) {
|
|
151
|
+
async tick({ trigger = 'schedule', events, rerunOf } = {}) {
|
|
150
152
|
const { job, logger } = this
|
|
151
153
|
if (this.running) {
|
|
152
154
|
logger.warn('[%s] previous run still going; skipping this tick', job.name)
|
|
@@ -156,18 +158,27 @@ export class JobRunner {
|
|
|
156
158
|
this.running = true
|
|
157
159
|
const firedAt = this.now()
|
|
158
160
|
const summary = events ? batchSummary(events) : undefined
|
|
159
|
-
this.current = { startedAt: firedAt.toISOString(), trigger, ...(summary ? { events: summary } : {}) }
|
|
161
|
+
this.current = { startedAt: firedAt.toISOString(), trigger, ...(summary ? { events: summary } : {}), ...(rerunOf ? { rerunOf: rerunOf.id } : {}) }
|
|
160
162
|
let result
|
|
161
163
|
let outcome = { status: 'failed' }
|
|
162
164
|
let thrown
|
|
163
165
|
let runId
|
|
164
166
|
try {
|
|
165
|
-
logger.info('[%s] start%s', job.name, trigger === 'manual' ? ' (run now)' : summary ? ` (${summary.count} event(s) on ${summary.channels.join(', ')})` : '')
|
|
167
|
+
logger.info('[%s] start%s', job.name, rerunOf ? ` (rerun of the run started ${rerunOf.startedAt})` : trigger === 'manual' ? ' (run now)' : summary ? ` (${summary.count} event(s) on ${summary.channels.join(', ')})` : '')
|
|
166
168
|
// A start line on its own shows a run that never finished (DSH stopped mid-run).
|
|
167
|
-
await this.record({ time: firedAt.toISOString(), job: job.name, event: 'start', ...(trigger !== 'schedule' ? { trigger } : {}), ...(summary ? { events: summary } : {}) })
|
|
168
|
-
runId = await this.history.begin(jobKey(job), { trigger, startedAt: firedAt.toISOString(), ...(summary ? { events: summary } : {}) })
|
|
169
|
-
|
|
170
|
-
|
|
169
|
+
await this.record({ time: firedAt.toISOString(), job: job.name, event: 'start', ...(trigger !== 'schedule' ? { trigger } : {}), ...(summary ? { events: summary } : {}), ...(rerunOf ? { rerunOf: rerunOf.id } : {}) })
|
|
170
|
+
runId = await this.history.begin(jobKey(job), { trigger, startedAt: firedAt.toISOString(), ...(summary ? { events: summary } : {}), ...(rerunOf ? { rerunOf: rerunOf.id } : {}) })
|
|
171
|
+
if (rerunOf) {
|
|
172
|
+
await this.history.update(jobKey(job), rerunOf.id, { rerun: { status: 'started', at: firedAt.toISOString(), runId } })
|
|
173
|
+
outcome = await this.continueRun(rerunOf)
|
|
174
|
+
} else {
|
|
175
|
+
outcome = await this.runOnce(firedAt, r => { result = r }, { trigger, events })
|
|
176
|
+
}
|
|
177
|
+
// The woken turn is watched until it ends: its answer is delivered, and a cut-off turn runs again.
|
|
178
|
+
if (outcome.status === 'woke' && outcome.messageId && outcome.sessionId && this.answer !== undefined) {
|
|
179
|
+
outcome = { ...outcome, turn: { status: 'pending', messageId: outcome.messageId } }
|
|
180
|
+
}
|
|
181
|
+
outcome = await this.deliverResult(outcome, result, { rerun: rerunOf !== undefined })
|
|
171
182
|
return outcome
|
|
172
183
|
} catch (error) {
|
|
173
184
|
thrown = describeError(error)
|
|
@@ -201,6 +212,7 @@ export class JobRunner {
|
|
|
201
212
|
queued: outcome.queued,
|
|
202
213
|
reuseNote: outcome.reuseNote,
|
|
203
214
|
targeted: outcome.targeted,
|
|
215
|
+
turn: outcome.turn,
|
|
204
216
|
archive: outcome.archive,
|
|
205
217
|
delivery: outcome.delivery,
|
|
206
218
|
error: thrown ?? outcome.error ?? result?.error,
|
|
@@ -215,7 +227,11 @@ export class JobRunner {
|
|
|
215
227
|
this.running = false
|
|
216
228
|
this.current = null
|
|
217
229
|
if (outcome.archive === 'pending' && runId !== undefined) this.watchArchive(outcome.sessionId, runId)
|
|
218
|
-
if (
|
|
230
|
+
if (runId !== undefined) {
|
|
231
|
+
const delivery = outcome.delivery?.status === 'pending' ? outcome.delivery : undefined
|
|
232
|
+
if (outcome.turn?.status === 'pending') this.watchTurn(outcome.sessionId, runId, outcome.turn.messageId, delivery)
|
|
233
|
+
else if (delivery?.message !== undefined) this.watchDelivery(outcome.sessionId, runId, delivery)
|
|
234
|
+
}
|
|
219
235
|
}
|
|
220
236
|
}
|
|
221
237
|
|
|
@@ -232,17 +248,21 @@ export class JobRunner {
|
|
|
232
248
|
* A gate that decided not to wake, and a run stopped by an unload, send
|
|
233
249
|
* nothing.
|
|
234
250
|
*/
|
|
235
|
-
async deliverResult({ messageId, ...outcome }, result) {
|
|
251
|
+
async deliverResult({ messageId, ...outcome }, result, { rerun = false } = {}) {
|
|
236
252
|
const target = this.deliveryTarget()
|
|
237
253
|
if (target === undefined) return outcome
|
|
238
254
|
const { job } = this
|
|
239
255
|
const where = { via: target.via, to: target.to }
|
|
240
256
|
if (outcome.status === 'woke') {
|
|
241
|
-
if (
|
|
242
|
-
return { ...outcome, delivery: { status: 'pending', ...where
|
|
257
|
+
if (outcome.turn?.status !== 'pending') return outcome
|
|
258
|
+
return { ...outcome, delivery: { status: 'pending', ...where } }
|
|
243
259
|
}
|
|
244
260
|
let text
|
|
245
|
-
if (outcome.status === 'wake-failed')
|
|
261
|
+
if (outcome.status === 'wake-failed') {
|
|
262
|
+
text = rerun
|
|
263
|
+
? `⚠️ ${job.name}: the run cut off by a DSH restart could not run again: ${outcome.error}`
|
|
264
|
+
: `⚠️ ${job.name}: could not wake the agent: ${outcome.error}`
|
|
265
|
+
}
|
|
246
266
|
else if (result !== undefined && !result.aborted && (outcome.status === 'done' || outcome.status === 'failed')) text = commandResultText(job, result)
|
|
247
267
|
else return outcome
|
|
248
268
|
const message = messageFromText(text, job.cwd || undefined)
|
|
@@ -264,7 +284,7 @@ export class JobRunner {
|
|
|
264
284
|
*/
|
|
265
285
|
async deliverMessage(target, message, { sessionId, waitMs, onWait }) {
|
|
266
286
|
const { job, logger } = this
|
|
267
|
-
const sent = await this.send(target, message, { job: job.name, ...(sessionId ? { sessionId } : {}) }, {
|
|
287
|
+
const sent = await this.send(target, message, { job: job.name, jobId: jobKey(job), ...(sessionId ? { sessionId } : {}) }, {
|
|
268
288
|
...(waitMs !== undefined ? { waitMs } : {}), ...(onWait ? { onWait } : {}),
|
|
269
289
|
})
|
|
270
290
|
const where = describeTarget(target)
|
|
@@ -283,81 +303,154 @@ export class JobRunner {
|
|
|
283
303
|
}
|
|
284
304
|
|
|
285
305
|
/**
|
|
286
|
-
* Deliver a
|
|
287
|
-
*
|
|
288
|
-
*
|
|
289
|
-
*
|
|
290
|
-
* is not running is waited for (see deliver.js sendMessage). Left pending
|
|
291
|
-
* when the plugin unloads, for the next copy to finish (see
|
|
292
|
-
* resumeDeliveries).
|
|
306
|
+
* Deliver a message kept with a pending delivery (a command's output, a
|
|
307
|
+
* failure note) in the background and save the outcome in the run's
|
|
308
|
+
* history. Left pending when the plugin unloads, for the next copy to
|
|
309
|
+
* finish (see resumeRuns).
|
|
293
310
|
*/
|
|
294
311
|
watchDelivery(sessionId, runId, pending) {
|
|
312
|
+
return this.background(this.deliveryWork(sessionId, runId, pending, () => this.sendPending(sessionId, runId, pending, pending.message)))
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* Wait in the background for the turn a woken prompt started, then save
|
|
317
|
+
* how it ended and deliver its final answer when the run has a pending
|
|
318
|
+
* delivery. An empty answer or exactly [SILENT] sends nothing. A turn DSH
|
|
319
|
+
* cut off (a restart or reload disposed it) delivers nothing and is marked
|
|
320
|
+
* for one rerun (see markCutOff). Left pending when the plugin unloads:
|
|
321
|
+
* the turn may still be running, and the next copy watches it again.
|
|
322
|
+
*/
|
|
323
|
+
watchTurn(sessionId, runId, messageId, pending) {
|
|
295
324
|
const { job, logger } = this
|
|
296
|
-
const
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
logger.warn('[%s] %s; waiting for it to deliver the result', job.name, error)
|
|
305
|
-
save({ ...pending, error }).then(() => logEntry({ status: 'waiting', error })).catch(() => {})
|
|
306
|
-
}
|
|
307
|
-
const send = async (message) => {
|
|
308
|
-
const delivery = await this.deliverMessage(target, message, { sessionId, onWait })
|
|
309
|
-
// Unloading: the next copy of the plugin sends it.
|
|
310
|
-
if (delivery.status === 'pending') {
|
|
311
|
-
await logEntry({ status: 'pending', error: `${delivery.error}; left for the next start` })
|
|
312
|
-
return undefined
|
|
313
|
-
}
|
|
314
|
-
return delivery
|
|
315
|
-
}
|
|
316
|
-
const watch = (async () => {
|
|
325
|
+
const work = async () => {
|
|
326
|
+
const answer = await this.answer(sessionId, messageId, { signal: this.signal })
|
|
327
|
+
if ('pending' in answer || this.signal?.aborted) return undefined
|
|
328
|
+
const cut = 'text' in answer && cutOff(answer)
|
|
329
|
+
if ('text' in answer && !cut) await this.checks?.recheck(messageId, answer.text, { sessionId, signal: this.signal })
|
|
330
|
+
this.checks?.forget(messageId)
|
|
331
|
+
const reason = 'error' in answer ? 'error' : answer.reason
|
|
332
|
+
await this.history.update(jobKey(job), runId, { turn: { status: cut ? 'cut-off' : 'ended', messageId, ...(reason ? { reason } : {}) } })
|
|
317
333
|
let delivery
|
|
318
|
-
if (pending
|
|
319
|
-
delivery =
|
|
334
|
+
if (pending === undefined) {
|
|
335
|
+
delivery = undefined
|
|
336
|
+
} else if ('error' in answer) {
|
|
337
|
+
delivery = { status: 'failed', via: pending.via, to: pending.to ?? '', at: this.now().toISOString(), error: answer.error }
|
|
338
|
+
logger.warn('[%s] no answer to deliver from session %s: %s', job.name, sessionId, answer.error)
|
|
320
339
|
} else {
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
if ('error' in answer) {
|
|
327
|
-
delivery = { status: 'failed', ...target, at: this.now().toISOString(), error: answer.error }
|
|
328
|
-
logger.warn('[%s] no answer to deliver from session %s: %s', job.name, sessionId, answer.error)
|
|
340
|
+
const message = cut ? undefined : messageFromText(answer.text, agentSettings(job, this.defaults).cwd)
|
|
341
|
+
if (message === undefined) {
|
|
342
|
+
const ended = cut ? `turn cut off: ${answer.cause}` : answer.reason && answer.reason !== 'completed' ? `turn ended: ${answer.reason}` : undefined
|
|
343
|
+
delivery = { status: 'silent', via: pending.via, to: pending.to ?? '', at: this.now().toISOString(), ...(ended ? { error: ended } : {}) }
|
|
344
|
+
logger.info('[%s] nothing to deliver from session %s', job.name, sessionId)
|
|
329
345
|
} else {
|
|
330
|
-
|
|
331
|
-
if (message === undefined) {
|
|
332
|
-
delivery = { status: 'silent', ...target, at: this.now().toISOString(), ...(answer.reason && answer.reason !== 'completed' ? { error: `turn ended: ${answer.reason}` } : {}) }
|
|
333
|
-
logger.info('[%s] nothing to deliver from session %s', job.name, sessionId)
|
|
334
|
-
} else {
|
|
335
|
-
delivery = await send(message)
|
|
336
|
-
}
|
|
346
|
+
delivery = await this.sendPending(sessionId, runId, pending, message)
|
|
337
347
|
}
|
|
338
348
|
}
|
|
349
|
+
if (cut) await this.markCutOff(sessionId, runId)
|
|
350
|
+
return delivery
|
|
351
|
+
}
|
|
352
|
+
if (pending === undefined) {
|
|
353
|
+
return this.background(work().catch((error) => {
|
|
354
|
+
logger.warn('[%s] turn in session %s not watched: %s', job.name, sessionId, describeError(error))
|
|
355
|
+
}))
|
|
356
|
+
}
|
|
357
|
+
return this.background(this.deliveryWork(sessionId, runId, pending, work))
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/** Run a delivery, then save and log its outcome; undefined from `work` means it stays pending. */
|
|
361
|
+
async deliveryWork(sessionId, runId, pending, work) {
|
|
362
|
+
const { job, logger } = this
|
|
363
|
+
const target = { via: pending.via, to: pending.to ?? '' }
|
|
364
|
+
try {
|
|
365
|
+
const delivery = await work()
|
|
339
366
|
if (delivery === undefined) return
|
|
340
|
-
await
|
|
341
|
-
await
|
|
342
|
-
}
|
|
367
|
+
await this.history.update(jobKey(job), runId, { delivery })
|
|
368
|
+
await this.logDelivery(sessionId, target, delivery)
|
|
369
|
+
} catch (error) {
|
|
343
370
|
logger.warn('[%s] delivery from session %s failed: %s', job.name, sessionId, describeError(error))
|
|
344
|
-
if (!this.signal?.aborted)
|
|
345
|
-
}
|
|
371
|
+
if (!this.signal?.aborted) await this.history.update(jobKey(job), runId, { delivery: { status: 'failed', ...target, at: this.now().toISOString(), error: describeError(error) } })
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
/**
|
|
376
|
+
* Send one message of a pending delivery. A service that is not running is
|
|
377
|
+
* waited for (see deliver.js sendMessage), shown on the page and in the
|
|
378
|
+
* run log meanwhile. Resolves undefined when the plugin unloads first.
|
|
379
|
+
*/
|
|
380
|
+
async sendPending(sessionId, runId, pending, message) {
|
|
381
|
+
const { job, logger } = this
|
|
382
|
+
const target = { via: pending.via, to: pending.to ?? '' }
|
|
383
|
+
const onWait = (error) => {
|
|
384
|
+
logger.warn('[%s] %s; waiting for it to deliver the result', job.name, error)
|
|
385
|
+
this.history.update(jobKey(job), runId, { delivery: { ...pending, error } })
|
|
386
|
+
.then(() => this.logDelivery(sessionId, target, { status: 'waiting', error })).catch(() => {})
|
|
387
|
+
}
|
|
388
|
+
const delivery = await this.deliverMessage(target, message, { sessionId, onWait })
|
|
389
|
+
// Unloading: the next copy of the plugin sends it, from the kept message
|
|
390
|
+
// (the turn it came from is already recorded as ended).
|
|
391
|
+
if (delivery.status === 'pending') {
|
|
392
|
+
await this.history.update(jobKey(job), runId, { delivery: { ...pending, message } })
|
|
393
|
+
await this.logDelivery(sessionId, target, { status: 'pending', error: `${delivery.error}; left for the next start` })
|
|
394
|
+
return undefined
|
|
395
|
+
}
|
|
396
|
+
return delivery
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
logDelivery(sessionId, target, delivery) {
|
|
400
|
+
return this.record({
|
|
401
|
+
time: this.now().toISOString(), job: this.job.name, event: 'delivery', ...(sessionId ? { sessionId } : {}),
|
|
402
|
+
status: delivery.status, via: target.via, to: target.to, ...(delivery.error ? { error: delivery.error } : {}),
|
|
403
|
+
})
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/** Keep a background promise in `settling` until it ends. */
|
|
407
|
+
background(promise) {
|
|
408
|
+
const watch = promise.finally(() => this.settling.delete(watch))
|
|
346
409
|
this.settling.add(watch)
|
|
347
410
|
return watch
|
|
348
411
|
}
|
|
349
412
|
|
|
350
|
-
/**
|
|
351
|
-
|
|
413
|
+
/**
|
|
414
|
+
* A run's turn was cut off: save that its rerun is pending and tell the
|
|
415
|
+
* controller, which reruns it once DSH is back. A rerun is never rerun
|
|
416
|
+
* again, so a turn that keeps getting cut off does not loop.
|
|
417
|
+
*/
|
|
418
|
+
async markCutOff(sessionId, runId) {
|
|
419
|
+
const { job, logger } = this
|
|
420
|
+
const run = this.history.runs(jobKey(job)).find(saved => saved.id === runId)
|
|
421
|
+
const time = this.now().toISOString()
|
|
422
|
+
if (run?.rerunOf !== undefined) {
|
|
423
|
+
const note = 'a rerun is not run again'
|
|
424
|
+
await this.history.update(jobKey(job), runId, { rerun: { status: 'skipped', at: time, note } })
|
|
425
|
+
await this.record({ time, job: job.name, event: 'rerun-skipped', runId, sessionId, note })
|
|
426
|
+
logger.warn('[%s] the rerun in session %s was cut off too; %s', job.name, sessionId, note)
|
|
427
|
+
return
|
|
428
|
+
}
|
|
429
|
+
await this.history.update(jobKey(job), runId, { rerun: { status: 'pending' } })
|
|
430
|
+
await this.record({ time, job: job.name, event: 'cut-off', runId, sessionId })
|
|
431
|
+
logger.warn('[%s] the turn in session %s was cut off before it finished; it runs again once DSH is back', job.name, sessionId)
|
|
432
|
+
this.onCutOff?.(runId)
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
/**
|
|
436
|
+
* After a restart or reload: pick up what an earlier copy of the plugin
|
|
437
|
+
* left pending. Turns are watched again (they may still be running, after
|
|
438
|
+
* a plugin reload or on a provider that outlives a restart), kept
|
|
439
|
+
* deliveries are sent, and cut-off runs go back to the controller for
|
|
440
|
+
* their rerun.
|
|
441
|
+
*/
|
|
442
|
+
async resumeRuns() {
|
|
352
443
|
for (const run of this.history.runs(jobKey(this.job))) {
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
this.
|
|
444
|
+
const delivery = run.delivery?.status === 'pending' ? run.delivery : undefined
|
|
445
|
+
// Runs saved before turns were tracked keep the prompt id on the delivery.
|
|
446
|
+
const messageId = run.turn === undefined ? delivery?.messageId : run.turn.status === 'pending' ? run.turn.messageId : undefined
|
|
447
|
+
if (delivery?.message !== undefined) {
|
|
448
|
+
this.watchDelivery(run.sessionId, run.id, delivery)
|
|
449
|
+
} else if (messageId && run.sessionId && this.answer !== undefined) {
|
|
450
|
+
this.expectCheck(messageId)
|
|
451
|
+
this.watchTurn(run.sessionId, run.id, messageId, delivery)
|
|
360
452
|
}
|
|
453
|
+
if (run.rerun?.status === 'pending') this.onCutOff?.(run.id)
|
|
361
454
|
}
|
|
362
455
|
}
|
|
363
456
|
|
|
@@ -412,12 +505,63 @@ export class JobRunner {
|
|
|
412
505
|
return sent.status === 'woke' ? { ...sent, messageId } : sent
|
|
413
506
|
}
|
|
414
507
|
|
|
508
|
+
/**
|
|
509
|
+
* Rerun a cut-off run: ask its own session to finish the job. The session
|
|
510
|
+
* already holds the job's prompt (with any command output and events) and
|
|
511
|
+
* whatever the cut-off turn did, so continuing there neither loses that
|
|
512
|
+
* input nor repeats finished steps. A session a person has taken over is
|
|
513
|
+
* left alone unless it is the job's own target.
|
|
514
|
+
* @param {object} original - The saved run that was cut off.
|
|
515
|
+
*/
|
|
516
|
+
async continueRun(original) {
|
|
517
|
+
const { job } = this
|
|
518
|
+
if (!original.sessionId) return { status: 'wake-failed', error: 'the cut-off run has no session' }
|
|
519
|
+
const settings = agentSettings(job, this.defaults)
|
|
520
|
+
const target = job.target ?? { kind: 'new' }
|
|
521
|
+
const text = buildRerunPrompt({
|
|
522
|
+
jobName: job.name,
|
|
523
|
+
...(job.source === 'tool' ? { jobId: jobKey(job) } : {}),
|
|
524
|
+
firedAt: formatLocalTime(new Date(original.startedAt), job.timeZone || undefined),
|
|
525
|
+
delivery: this.deliveryTarget(),
|
|
526
|
+
})
|
|
527
|
+
const messageId = randomUUID()
|
|
528
|
+
this.expectCheck(messageId)
|
|
529
|
+
const archive = target.kind !== 'session' && settings.autoArchive && this.settle !== undefined ? { archive: 'pending' } : {}
|
|
530
|
+
const fresh = target.kind === 'new'
|
|
531
|
+
const sent = await this.sendToTarget(original.sessionId, text, {
|
|
532
|
+
mayUnarchive: true,
|
|
533
|
+
ignoreHold: !fresh,
|
|
534
|
+
archive,
|
|
535
|
+
messageId,
|
|
536
|
+
fields: fresh ? { reused: true, sessionOpenedAt: original.sessionOpenedAt ?? original.startedAt } : { targeted: true },
|
|
537
|
+
})
|
|
538
|
+
if (sent.status !== 'woke') this.checks?.forget(messageId)
|
|
539
|
+
return sent.status === 'woke' ? { ...sent, messageId } : sent
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
/**
|
|
543
|
+
* Who sends this run's prompt, recorded as `source.principal` on it: the
|
|
544
|
+
* job, what started the run, and the event channels of an event run.
|
|
545
|
+
* @returns {{ kind: 'cron-job', channel: 'cron', id: string, name: string, trigger: string, events?: string[] }}
|
|
546
|
+
*/
|
|
547
|
+
promptPrincipal() {
|
|
548
|
+
const { job, current } = this
|
|
549
|
+
return {
|
|
550
|
+
kind: 'cron-job',
|
|
551
|
+
channel: 'cron',
|
|
552
|
+
id: jobKey(job),
|
|
553
|
+
name: job.name,
|
|
554
|
+
trigger: current?.rerunOf ? 'rerun' : current?.trigger ?? 'schedule',
|
|
555
|
+
...(current?.events?.channels?.length ? { events: [...current.events.channels] } : {}),
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
|
|
415
559
|
/** Have the answer to this prompt checked before its turn closes, when the job names a check. */
|
|
416
560
|
expectCheck(messageId) {
|
|
417
561
|
const command = this.job.agent?.answerCheck
|
|
418
562
|
if (!command || this.checks === undefined) return
|
|
419
563
|
const cwd = agentSettings(this.job, this.defaults).cwd
|
|
420
|
-
this.checks.expect(messageId, { job: this.job.name, command, ...(cwd ? { cwd } : {}) })
|
|
564
|
+
this.checks.expect(messageId, { job: this.job.name, jobId: jobKey(this.job), command, ...(cwd ? { cwd } : {}) })
|
|
421
565
|
}
|
|
422
566
|
|
|
423
567
|
/** Send the prompt to the target session, a reused one, or a new one. */
|
|
@@ -437,7 +581,7 @@ export class JobRunner {
|
|
|
437
581
|
if (previous !== undefined) {
|
|
438
582
|
try {
|
|
439
583
|
const sent = await this.withSessionLock(previous.sessionId, async () => {
|
|
440
|
-
const delivered = await this.reuse({ sessionId: previous.sessionId, text, messageId, mayUnarchive: settings.autoArchive })
|
|
584
|
+
const delivered = await this.reuse({ sessionId: previous.sessionId, text, messageId, principal: this.promptPrincipal(), mayUnarchive: settings.autoArchive })
|
|
441
585
|
// Inside the lock, so an earlier run's archive wait sees it was superseded.
|
|
442
586
|
this.latestRun.set(previous.sessionId, null)
|
|
443
587
|
return delivered
|
|
@@ -460,6 +604,7 @@ export class JobRunner {
|
|
|
460
604
|
const opened = await this.wake({
|
|
461
605
|
text,
|
|
462
606
|
messageId,
|
|
607
|
+
principal: this.promptPrincipal(),
|
|
463
608
|
title: sessionTitle(job.name, localTime),
|
|
464
609
|
...(job.agent.preset ? { agentPreset: job.agent.preset } : {}),
|
|
465
610
|
...(agentModel(job) ? { model: agentModel(job) } : {}),
|
|
@@ -493,21 +638,23 @@ export class JobRunner {
|
|
|
493
638
|
/**
|
|
494
639
|
* Send the prompt to the job's target session: an existing session the job
|
|
495
640
|
* names, or the one a new_once job opened. Delivered even when a person
|
|
496
|
-
* uses the session
|
|
497
|
-
*
|
|
641
|
+
* uses the session (unless `ignoreHold` is false, as for a rerun into a
|
|
642
|
+
* session the job opened for itself); that is what the target is for. An
|
|
643
|
+
* archived session is unarchived first when `mayUnarchive` is set.
|
|
644
|
+
* `fields` describe the run's session in its outcome.
|
|
498
645
|
* @returns {Promise<object>} The run outcome; `wake-failed` with the reason when not delivered.
|
|
499
646
|
*/
|
|
500
|
-
async sendToTarget(sessionId, text, { mayUnarchive, archive = {}, messageId }) {
|
|
647
|
+
async sendToTarget(sessionId, text, { mayUnarchive, ignoreHold = true, archive = {}, messageId, fields = { targeted: true } }) {
|
|
501
648
|
const { job, logger } = this
|
|
502
649
|
if (this.reuse === undefined) return { status: 'wake-failed', error: 'this host cannot deliver to existing sessions' }
|
|
503
650
|
try {
|
|
504
651
|
const sent = await this.withSessionLock(sessionId, async () => {
|
|
505
|
-
const delivered = await this.reuse({ sessionId, text, messageId, mayUnarchive, ignoreHold
|
|
652
|
+
const delivered = await this.reuse({ sessionId, text, messageId, principal: this.promptPrincipal(), mayUnarchive, ignoreHold })
|
|
506
653
|
this.latestRun.set(sessionId, null)
|
|
507
654
|
return delivered
|
|
508
655
|
})
|
|
509
656
|
logger.info('[%s] sent the prompt to its session %s%s', job.name, sessionId, sent?.queued ? ' (queued behind its current turn)' : '')
|
|
510
|
-
return { status: 'woke', sessionId,
|
|
657
|
+
return { status: 'woke', sessionId, ...fields, ...(sent?.queued ? { queued: true } : {}), ...archive }
|
|
511
658
|
} catch (error) {
|
|
512
659
|
const reason = describeError(error)
|
|
513
660
|
logger.warn('[%s] could not send the prompt to session %s: %s', job.name, sessionId, reason)
|
package/src/prompt.js
CHANGED
|
@@ -21,11 +21,7 @@ export const MAX_PROMPT_OUTPUT_BYTES = 64 * 1024
|
|
|
21
21
|
*/
|
|
22
22
|
export function buildAgentPrompt({ jobName, jobId, prompt, stdout, droppedBytes = 0, firedAt, delivery, events }) {
|
|
23
23
|
const when = `run at ${firedAt}${events === undefined ? '' : ', started by the events below'}`
|
|
24
|
-
const
|
|
25
|
-
? `This is a scheduled message from the user, sent by the cron job "${jobName}" (${when}).`
|
|
26
|
-
: `This is a scheduled message from the user, sent by the scheduled job "${jobName}" (id ${jobId}, ${when}).`)
|
|
27
|
-
+ (delivery === undefined ? '' : ` Your final answer is delivered ${delivery.to ? `to ${delivery.to} ` : ''}through ${delivery.via}; MEDIA:<path> lines in it are attached as files, and an answer of exactly [SILENT] sends nothing.`)
|
|
28
|
-
const parts = [header, '', prompt.trim()]
|
|
24
|
+
const parts = [header({ jobName, jobId, when }) + deliveryNote(delivery), '', prompt.trim()]
|
|
29
25
|
if (events !== undefined) parts.push('', ...eventBlock(events))
|
|
30
26
|
if (stdout === undefined) return parts.join('\n')
|
|
31
27
|
const { text, cut } = tailBytes(stdout.replace(/\s+$/, ''), MAX_PROMPT_OUTPUT_BYTES)
|
|
@@ -40,6 +36,37 @@ export function buildAgentPrompt({ jobName, jobId, prompt, stdout, droppedBytes
|
|
|
40
36
|
].join('\n')
|
|
41
37
|
}
|
|
42
38
|
|
|
39
|
+
/**
|
|
40
|
+
* Build the message that reruns a cut-off run in its own session: the job's
|
|
41
|
+
* prompt is already above it, together with whatever the cut-off turn did,
|
|
42
|
+
* so the agent is asked to finish the work rather than start over.
|
|
43
|
+
*
|
|
44
|
+
* @param {object} input
|
|
45
|
+
* @param {string} input.jobName
|
|
46
|
+
* @param {string} [input.jobId]
|
|
47
|
+
* @param {string} input.firedAt - Local time of the cut-off run.
|
|
48
|
+
* @param {{ via: string, to: string }} [input.delivery]
|
|
49
|
+
* @returns {string}
|
|
50
|
+
*/
|
|
51
|
+
export function buildRerunPrompt({ jobName, jobId, firedAt, delivery }) {
|
|
52
|
+
return [
|
|
53
|
+
header({ jobName, jobId, when: `rerun of the run at ${firedAt}` }) + deliveryNote(delivery),
|
|
54
|
+
'',
|
|
55
|
+
`Your turn on this job's message of ${firedAt} (above) was cut off before it finished, because DSH restarted or reloaded. Check what that turn already did, then finish the job without repeating what is done.`,
|
|
56
|
+
].join('\n')
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function header({ jobName, jobId, when }) {
|
|
60
|
+
return jobId === undefined
|
|
61
|
+
? `This is a scheduled message from the user, sent by the cron job "${jobName}" (${when}).`
|
|
62
|
+
: `This is a scheduled message from the user, sent by the scheduled job "${jobName}" (id ${jobId}, ${when}).`
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function deliveryNote(delivery) {
|
|
66
|
+
if (delivery === undefined) return ''
|
|
67
|
+
return ` Your final answer is delivered ${delivery.to ? `to ${delivery.to} ` : ''}through ${delivery.via}; MEDIA:<path> lines in it are attached as files, and an answer of exactly [SILENT] sends nothing.`
|
|
68
|
+
}
|
|
69
|
+
|
|
43
70
|
/**
|
|
44
71
|
* The events that started a run, one JSON object per line. Their content
|
|
45
72
|
* comes from outside DSH (a mail subject, a webhook body), so it is labelled
|
package/src/session.js
CHANGED
|
@@ -24,6 +24,7 @@ import { finalAnswer } from './deliver.js'
|
|
|
24
24
|
* @param {object} request
|
|
25
25
|
* @param {string} request.text - Message text.
|
|
26
26
|
* @param {string} [request.messageId] - Id of the message, so its answer can be found later.
|
|
27
|
+
* @param {object} [request.principal] - Who sends the message, recorded on its source.
|
|
27
28
|
* @param {string} request.title - Session title.
|
|
28
29
|
* @param {string} [request.agentPreset] - Agent preset id; the host default when omitted.
|
|
29
30
|
* @param {string} [request.cwd] - Session directory; the host default when omitted.
|
|
@@ -31,7 +32,7 @@ import { finalAnswer } from './deliver.js'
|
|
|
31
32
|
* @param {{ warn: Function }} logger
|
|
32
33
|
* @returns {Promise<string>} The new session id.
|
|
33
34
|
*/
|
|
34
|
-
export async function openAgentSession(ctx, { text, messageId, title, agentPreset, cwd, model }, logger) {
|
|
35
|
+
export async function openAgentSession(ctx, { text, messageId, principal, title, agentPreset, cwd, model }, logger) {
|
|
35
36
|
const controller = ctx.get('sessionController')
|
|
36
37
|
const sessions = ctx.get('sessions')
|
|
37
38
|
if (controller === undefined || sessions === undefined) {
|
|
@@ -51,7 +52,7 @@ export async function openAgentSession(ctx, { text, messageId, title, agentPrese
|
|
|
51
52
|
await joinWorkspace(ctx, sessionId, cwd, logger)
|
|
52
53
|
nameSession(ctx, agent, title, logger)
|
|
53
54
|
|
|
54
|
-
agent.followup(userMessage(text, messageId))
|
|
55
|
+
agent.followup(userMessage(text, messageId, principal))
|
|
55
56
|
if (!await sessions.flush(agent.session)) {
|
|
56
57
|
throw new Error('session persistence did not acknowledge the message')
|
|
57
58
|
}
|
|
@@ -83,12 +84,13 @@ export async function openAgentSession(ctx, { text, messageId, title, agentPrese
|
|
|
83
84
|
* @param {string} request.sessionId
|
|
84
85
|
* @param {string} request.text
|
|
85
86
|
* @param {string} [request.messageId] - Id of the message, so its answer can be found later.
|
|
87
|
+
* @param {object} [request.principal] - Who sends the message, recorded on its source.
|
|
86
88
|
* @param {boolean} [request.mayUnarchive]
|
|
87
89
|
* @param {boolean} [request.ignoreHold] - Deliver even to a pinned session or one a person uses.
|
|
88
90
|
* @returns {Promise<{ sessionId: string, queued: boolean, unarchived: boolean }>}
|
|
89
91
|
* `queued`: the session was busy and the message waits for its next turn.
|
|
90
92
|
*/
|
|
91
|
-
export async function deliverToSession(ctx, { sessionId, text, messageId, mayUnarchive = false, ignoreHold = false }) {
|
|
93
|
+
export async function deliverToSession(ctx, { sessionId, text, messageId, principal, mayUnarchive = false, ignoreHold = false }) {
|
|
92
94
|
const controller = ctx.get('sessionController')
|
|
93
95
|
const sessions = ctx.get('sessions')
|
|
94
96
|
if (controller === undefined || sessions === undefined) {
|
|
@@ -107,7 +109,7 @@ export async function deliverToSession(ctx, { sessionId, text, messageId, mayUna
|
|
|
107
109
|
await registry.unarchiveSession(sessionId)
|
|
108
110
|
}
|
|
109
111
|
const queued = agent.status !== undefined && agent.status !== 'idle'
|
|
110
|
-
agent.followup(userMessage(text, messageId))
|
|
112
|
+
agent.followup(userMessage(text, messageId, principal))
|
|
111
113
|
if (!await sessions.flush(agent.session)) {
|
|
112
114
|
throw new Error('session persistence did not acknowledge the message')
|
|
113
115
|
}
|
|
@@ -220,7 +222,7 @@ export const ANSWER_ATTEMPTS = 120
|
|
|
220
222
|
* @param {AbortSignal} [options.signal] - Plugin unload: resolves `{ pending: true }`.
|
|
221
223
|
* @param {number} [options.retryMs]
|
|
222
224
|
* @param {number} [options.attempts]
|
|
223
|
-
* @returns {Promise<{ pending: true } | { text: string, reason?: string } | { error: string }>}
|
|
225
|
+
* @returns {Promise<{ pending: true } | { text: string, reason?: string, cause?: string } | { error: string }>}
|
|
224
226
|
*/
|
|
225
227
|
export async function waitForAnswer(ctx, sessionId, messageId, {
|
|
226
228
|
signal, retryMs = ANSWER_RETRY_MS, attempts = ANSWER_ATTEMPTS, serviceWaitMs = SERVICE_WAIT_MS,
|
|
@@ -235,7 +237,7 @@ export async function waitForAnswer(ctx, sessionId, messageId, {
|
|
|
235
237
|
await agent.whenIdle().catch(() => {})
|
|
236
238
|
if (signal?.aborted) return { pending: true }
|
|
237
239
|
const answer = finalAnswer(agent.session?.log ?? [], messageId)
|
|
238
|
-
if (answer.done) return { text: answer.text ?? '', reason: answer.reason }
|
|
240
|
+
if (answer.done) return { text: answer.text ?? '', reason: answer.reason, ...(answer.cause ? { cause: answer.cause } : {}) }
|
|
239
241
|
if (attempt >= attempts) return { error: 'the prompt never reached a finished turn' }
|
|
240
242
|
await sleep(retryMs, signal)
|
|
241
243
|
if (signal?.aborted) return { pending: true }
|
|
@@ -283,14 +285,19 @@ function describe(error) {
|
|
|
283
285
|
|
|
284
286
|
/**
|
|
285
287
|
* A user-role message from a scheduled source. `kind: 'schedule'` makes the
|
|
286
|
-
* Web GUI show it as a scheduled run.
|
|
288
|
+
* Web GUI show it as a scheduled run. `principal`, DSH's field for the caller
|
|
289
|
+
* behind a user message, names the job that sent it (see
|
|
290
|
+
* `JobRunner.promptPrincipal`), so session readers need not parse the text.
|
|
291
|
+
* @param {string} text
|
|
292
|
+
* @param {string} [id]
|
|
293
|
+
* @param {object} [principal]
|
|
287
294
|
*/
|
|
288
|
-
export function userMessage(text, id = randomUUID()) {
|
|
295
|
+
export function userMessage(text, id = randomUUID(), principal) {
|
|
289
296
|
return deepFreeze({
|
|
290
297
|
id,
|
|
291
298
|
role: 'user',
|
|
292
299
|
content: [{ type: 'text', text }],
|
|
293
|
-
source: { kind: 'schedule' },
|
|
300
|
+
source: { kind: 'schedule', ...(principal ? { principal: { ...principal } } : {}) },
|
|
294
301
|
})
|
|
295
302
|
}
|
|
296
303
|
|
package/tools.js
CHANGED
|
@@ -49,7 +49,7 @@ export function toolSchemas(prefix) {
|
|
|
49
49
|
on: {
|
|
50
50
|
type: 'array',
|
|
51
51
|
items: { type: 'string' },
|
|
52
|
-
description: `Event channels that start a run, with * for any characters (mail.
|
|
52
|
+
description: `Event channels that start a run, with * for any characters (mail.inbox, ci.*, dsh.started). Events come from \`dsh-cron-event <channel>\` (any script or hook), from watchers (${prefix}_watch), and dsh.started once after each DSH start. Events within about 30 s run the job once; the command gets them as JSON on stdin and the prompt gets them appended as untrusted data. A job with on may leave out the schedule; keep a slower one as a safety net when events can be missed.`,
|
|
53
53
|
},
|
|
54
54
|
once: { type: 'boolean', description: 'End the job after its first run that was not started by hand (an event or a scheduled run). With on: dsh.started, it waits for the next DSH start.' },
|
|
55
55
|
}
|
|
@@ -75,7 +75,7 @@ export function toolSchemas(prefix) {
|
|
|
75
75
|
watch: object({
|
|
76
76
|
action: { type: 'string', enum: ['create', 'delete', 'list'], description: 'create starts a new watcher; delete stops and removes one; list shows every watcher with its state.' },
|
|
77
77
|
id: { type: 'string', description: 'Watcher id: letters, digits, _ . - (create, delete).' },
|
|
78
|
-
channel: { type: 'string', description: 'Channel its output lines are emitted on, such as mail.
|
|
78
|
+
channel: { type: 'string', description: 'Channel its output lines are emitted on, such as mail.inbox (create).' },
|
|
79
79
|
command: { type: 'string', description: 'Shell command run with bash that keeps running and prints one line per change (create). A JSON object line is the event\'s data (its "id" field dedupes), any other line its text; {"wakeAgent": false} lines are ignored. It is restarted with backoff when it exits; down for 15 minutes sends one alert. It gets DSH_CRON_STATE_DIR, a directory for its cursor, so it can catch up after a restart.' },
|
|
80
80
|
cwd: { type: 'string', description: 'Working directory; defaults to this session\'s (create).' },
|
|
81
81
|
once: { type: 'boolean', description: 'Run the command one time and remove the watcher when it exits, for a one-off wait such as `gh run watch 123 --exit-status >/dev/null; echo "{\\"exit\\": $?}"` (create).' },
|