@goodandready/dsh-cron 0.1.24 → 0.2.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.
Files changed (15) hide show
  1. package/README.md +117 -82
  2. package/docs/README.ru.md +133 -85
  3. package/docs/README.zh.md +140 -82
  4. package/docs/design/DESIGN.md +44 -36
  5. package/lib/chat-start.js +2 -2
  6. package/lib/client.js +647 -409
  7. package/lib/http-utils.js +81 -0
  8. package/lib/index.js +342 -384
  9. package/lib/integrations.js +0 -1
  10. package/lib/prompt.js +42 -40
  11. package/lib/runner.js +48 -34
  12. package/lib/scheduler.js +33 -32
  13. package/lib/store.js +1 -1
  14. package/lib/telegram.js +27 -13
  15. package/package.json +1 -1
package/README.md CHANGED
@@ -31,11 +31,10 @@ Autonomous AI agents often need to perform recurring duties: generating daily mo
31
31
 
32
32
  **`@goodandready/dsh-cron`** is a native full-stack scheduling and background automation plugin for DeepSeek Harness. It bridges standard cron expressions and natural interval syntax with autonomous agent execution, providing:
33
33
 
34
- 1. **Rich Visual Task Manager**: A dedicated sidebar navigation button and full-featured visual overlay to inspect, filter, pause, trigger, and create recurring tasks.
35
- 2. **Interactive "Create with DSH" Workflow**: Chat directly with your agent to translate high-level requirements into scheduled tasks, complete with custom model selection and prompt synthesis.
36
- 3. **Chat Slash Commands (`/cron`)**: Fast command-line control directly from the chat prompt (`/cron list`, `/cron add`, `/cron pause`, `/cron run`).
37
- 4. **Autonomous AI Tool Calling**: Gives agents native tools (`cron_schedule_task`, `cron_list_tasks`, `cron_toggle_task`) so they can schedule their own follow-up executions during conversations.
38
- 5. **Robust Scheduler & Atomic Storage**: Built on `croner` with timezone support, interval aliases (`every 15m`, `daily`, `weekdays`), atomic file persistence, and run execution histories.
34
+ 1. **Rich Visual Task Manager** — a sidebar button and a full-featured panel to inspect, filter, pause, trigger, and create recurring tasks.
35
+ 2. **Interactive "Create with DSH" Workflow** — chat with your agent to translate high-level requirements into a well-formed scheduled task.
36
+ 3. **Autonomous AI Tool Calling** — native `cron_*` tools let agents schedule their own follow-up executions during conversations.
37
+ 4. **Robust Scheduler & Atomic Storage** — built on `croner` with interval aliases, one-shot delays, atomic file persistence, run histories, and cost tracking.
39
38
 
40
39
  ---
41
40
 
@@ -45,30 +44,32 @@ Autonomous AI agents often need to perform recurring duties: generating daily mo
45
44
  graph TD
46
45
  subgraph Client ["Web Client Surface (DSH UI)"]
47
46
  SidebarBtn["Sidebar Clock Action<br/>(DSH Client UI Slot)"]
48
- Overlay["Visual Task Manager Modal<br/>(Tabs: All, Active, Paused, History)"]
49
- CreateWithDSH["'Create with DSH' Modal<br/>(Model Picker & Task Prompt)"]
50
- ManualForm["Manual Task Creation Modal<br/>(Cron Expression, Timezone, Model)"]
51
- SlashCmd["Slash Command Parser<br/>(/cron add, list, pause, run)"]
47
+ Overlay["Visual Task Manager Panel<br/>(Tabs: All, Active, Paused, Completed)"]
48
+ CreateWithDSH["'Create with DSH' Dialog<br/>(natural language task)"]
49
+ ManualForm["Manual Task Form<br/>(Cron Expression, Timeout, Overlap, Model)"]
50
+ SettingsCard["Settings Card<br/>(Telegram / Kanban integration)"]
52
51
  end
53
52
 
54
53
  subgraph Server ["Server Runtime (Cordis & DSH Services)"]
55
- HttpRoutes["HTTP REST API Endpoints<br/>(/dsh-cron/tasks, /models, /chat-start)"]
56
- AgentTools["AI Tool Calling Gateway<br/>(cron_schedule_task, cron_list_tasks)"]
57
- Scheduler["TaskScheduler Engine<br/>(Croner instance management)"]
54
+ HttpRoutes["HTTP REST API<br/>(/dsh-cron/*)"]
55
+ AgentTools["AI Tool Calling Gateway<br/>(cron_create_task, cron_list_tasks, ...)"]
56
+ Scheduler["TaskScheduler Engine<br/>(Croner instances + one-shot timers)"]
58
57
  Store["Atomic TaskStore<br/>(tasks.json with atomic write)"]
59
58
  AgentRunner["Agent Session Dispatcher<br/>(Executes prompt with chosen model)"]
59
+ Notify["Delivery<br/>(Telegram Bot API, dsh-kanban cards)"]
60
60
  end
61
61
 
62
62
  SidebarBtn --> Overlay
63
63
  Overlay --> CreateWithDSH
64
64
  Overlay --> ManualForm
65
- CreateWithDSH -->|POST /chat-start| HttpRoutes
65
+ SettingsCard --> HttpRoutes
66
+ CreateWithDSH -->|POST /chat/start| HttpRoutes
66
67
  ManualForm -->|POST /tasks| HttpRoutes
67
- SlashCmd -->|Command dispatch| HttpRoutes
68
68
  HttpRoutes --> Scheduler
69
69
  AgentTools --> Scheduler
70
70
  Scheduler --> Store
71
- Scheduler -->|Trigger on interval/cron| AgentRunner
71
+ Scheduler -->|Trigger on interval/one-shot| AgentRunner
72
+ Scheduler --> Notify
72
73
  ```
73
74
 
74
75
  ---
@@ -76,63 +77,76 @@ graph TD
76
77
  ## ✨ Features & Capabilities
77
78
 
78
79
  ### 1. Visual Task Manager & Sidebar Action
79
- Click the clock icon in the DSH sidebar (positioned conveniently next to Kanban and Chat) to open the management overlay:
80
- * **Status Filter Tabs**: Seamlessly toggle between **All**, **Active**, **Paused**, and **Completed** tasks.
81
- * **Instant Action Menu**: Trigger manual one-off executions (`Run Now`), pause/resume intervals, or delete obsolete schedules with confirmation safeguards.
82
- * **1-Click Preset Templates**: Quickly scaffold common workflows like *Daily Development Digest*, *Weekly Repo Review*, and *Health Heartbeat*.
83
- * **Execution History**: Expand any task card to review previous execution timestamps, elapsed durations, exit statuses, and generated outputs.
84
-
85
- ### 2. "Create with DSH" AI Chat Modal
86
- Transform natural language into scheduled jobs without manually guessing cron expressions:
80
+ Click the clock icon in the DSH sidebar (positioned next to the new-session button) to open the management panel:
81
+ * **Status Filter Tabs**: toggle between **All**, **Active**, **Paused**, and **Completed** tasks.
82
+ * **Instant Action Menu**: trigger manual one-off executions (**Run Now**), pause/resume schedules, or delete obsolete tasks with a confirmation step.
83
+ * **1-Click Preset Templates**: scaffold common workflows like *Daily digest*, *Weekly review*, and *Follow-up monitor*.
84
+ * **Execution History**: open any task card to review previous runs — timestamps, durations, statuses (success / failed / timeout / skipped / missed), outputs, and errors.
85
+ * **Aggregated Stats Bar**: live dashboard with active task count, total runs, total token consumption, and the estimated dollar spend.
86
+
87
+ ### 2. "Create with DSH" Dialog
88
+ Transform natural language into a scheduled job without guessing cron syntax:
87
89
  1. Click **Create ⌄** ➔ **Create with DSH**.
88
- 2. Select your target AI provider and model from the live model dropdown.
89
- 3. Describe what you want the agent to automate (e.g. *"Check open PRs every weekday at 9:00 AM and draft review comments"*).
90
- 4. The plugin automatically spawns a dedicated agent session pre-injected with scheduler system instructions to formulate the task and register it into `TaskStore`.
90
+ 2. Describe what you want to automate (e.g. *"Check open PRs every weekday at 9:00 and draft review comments"*).
91
+ 3. The plugin spawns a dedicated agent session pre-injected with scheduler instructions. The agent clarifies the details with you — LLM vs no-LLM shell task, the exact cron expression, an economical model from those available in your DSH installation, and whether a "silent rule" (alert only on new events or failures) should apply — and registers the task through the `cron_create_task` tool only after your confirmation.
91
92
 
92
- ### 3. Chat Slash Command (`/cron`)
93
- For keyboard-first workflows, manage tasks directly inside the chat window:
93
+ ### 3. Agent Tools (Tool Calling)
94
+ Autonomous agents can manage schedules directly:
94
95
 
95
- | Command | Syntax | Description |
96
- |:---|:---|:---|
97
- | `/cron list` | `/cron list` | Lists all registered tasks with IDs, schedules, and active statuses |
98
- | `/cron add` | `/cron add "<schedule>" <prompt>` | Creates a task. Example: `/cron add "every 2h" Run git fetch and summarize changes` |
99
- | `/cron pause` | `/cron pause <id>` | Pauses a running schedule without deleting its configuration |
100
- | `/cron resume` | `/cron resume <id>` | Resumes a previously paused task schedule |
101
- | `/cron run` | `/cron run <id>` | Triggers immediate out-of-band execution of the task |
102
- | `/cron delete` | `/cron delete <id>` | Permanently removes the task from the schedule |
96
+ | Tool | Description |
97
+ |:---|:---|
98
+ | `cron_create_task` | Creates a scheduled task: `title`, `schedule`, `prompt`, optional `type` (`llm`/`script`), `delivery`, `provider`, `model`, `notifyTelegram`, `onlyOnFailure`, `timeoutSeconds`, `overlapPolicy`, `kanbanMode` |
99
+ | `cron_schedule_task` | Alias of `cron_create_task` kept for compatibility with existing agent prompts |
100
+ | `cron_list_tasks` | Lists tasks with statuses, next run timestamps, token totals, and cost estimates |
101
+ | `cron_pause_task` | Pauses a schedule without deleting its configuration |
102
+ | `cron_resume_task` | Resumes a paused schedule |
103
+ | `cron_delete_task` | Permanently removes a task and its history |
104
+ | `cron_run_task` | Triggers an immediate out-of-band run |
105
+
106
+ Example invocation the model can make during a conversation:
107
+
108
+ ```
109
+ cron_create_task({
110
+ "title": "Morning digest",
111
+ "schedule": "0 8 * * 1-5",
112
+ "prompt": "Prepare a brief morning digest of active tasks and open tickets.",
113
+ "type": "llm",
114
+ "delivery": "isolated"
115
+ })
116
+ ```
103
117
 
104
- ### 4. Agent Tools (Tool Calling)
105
- When autonomous agents need to set up delayed or recurring actions, they can invoke these tools:
118
+ ### 4. Schedule Expression Syntax
119
+ Powered by `croner`, supporting standard 5-field cron expressions plus user-friendly aliases:
106
120
 
107
- * **`cron_schedule_task`**: Schedules a recurring or interval-based task with `name`, `schedule`, `prompt`, and optional `model` override.
108
- * **`cron_list_tasks`**: Retrieves an overview of active schedules and next scheduled run timestamps.
109
- * **`cron_toggle_task`**: Enables or disables an existing task by `id`.
121
+ * `0 9 * * 1-5` — weekdays at 09:00
122
+ * `*/15 * * * *` — every 15 minutes
123
+ * `0 0 * * 0` — every Sunday at midnight
124
+ * `every 10m` / `every 2h` / `every 30s` — natural duration intervals
125
+ * `daily` / `hourly` / `weekdays` shortcuts
126
+ * **One-shot tasks**: `at: 2026-09-05T15:00:00Z` (exact ISO timestamp) or relative delays `in 20m` / `in 2h` (Russian aliases such as `через 15 минут` are accepted too). One-shot tasks flip to `completed` automatically after their single run and are listed under the **Completed** tab.
110
127
 
111
- ### 6. Telegram Notifications & Delivery Routing
128
+ ### 5. Telegram Notifications & Delivery Routing
112
129
  Direct integration with the Telegram Bot API delivers execution reports and error traces straight to your messenger:
113
130
 
114
- * **Auto-Detected or Custom Credentials**: Enter a custom `botToken` and `chatId` in the UI settings dialog, or automatically inherit default credentials from `dsh-messenger-gateway` in `settings.yaml`.
115
- * **'Only on Failure' Mode (Issue #24)**: Prevent notification spam by enabling `onlyOnFailure` globally or on individual tasks. Clean runs remain silent, while non-zero exit codes or agent exceptions immediately dispatch an alert with stdout/stderr traces.
116
- * **Markdown Formatting**: Messages are formatted with status badges (✅ / ❌), execution duration in milliseconds, schedule descriptions, and monospace code blocks.
117
- * **Test Dispatch Button**: Verify Telegram connectivity on the spot before scheduling critical production jobs.
131
+ * **Auto-detected or custom credentials** — enter a custom `botToken` and `chatId` in the settings dialog, or let the plugin inherit defaults from the `dsh-messenger-gateway` section of your DSH `settings.yaml` (best-effort fallback).
132
+ * **Only-on-failure mode** — enable `onlyOnFailure` globally or per task. Clean runs stay silent; failures (`error` or `timeout` statuses) dispatch an alert with the error trace.
133
+ * **Markdown formatting** — messages carry status badges (✅ / ❌), duration, schedule description, and monospace output blocks; dynamic values are escaped so odd titles cannot break the message.
134
+ * **Test dispatch button** — verify Telegram connectivity on the spot before scheduling critical jobs.
118
135
 
119
- ### 7. Overlap Policies & Execution Timeout Control (Issues #11, #17)
120
- Prevent rogue processes from consuming server resources or stacking concurrent duplicate executions:
136
+ ### 6. Kanban Integration & Cost Meter
137
+ * **Automatic Kanban cards** — with `kanbanMode` set to `on_failure` or `always`, the plugin creates cards in `dsh-kanban` (`on_failure` → *Backlog* on `error`/`timeout`; `always` → *Done*/*Backlog* on completion).
138
+ * **Token & execution cost meter** — token consumption (input, output, cache reads) is tracked per run and per task, with USD estimates from a built-in pricing table and an aggregated analytics bar.
121
139
 
122
- * **Execution Timeout (`timeoutSeconds`)**: Automatically cancels agent sessions or kills shell subprocesses when the configured run time limit is reached (default: 1800s / 30m). Prevents hung tasks and records a descriptive timeout failure in run logs.
123
- * **Overlap Policy (`overlapPolicy`)**: Controls scheduler behavior when a scheduled tick fires while the previous execution is still running:
124
- * **`skip`** (default): Drops the overlapping run and records a `skipped` status entry in the run history without spamming.
125
- * **`queue`**: Queues the next execution and starts it automatically as soon as the active job completes.
126
- * **`replace`**: Aborts the stuck/active run immediately via `AbortController` and launches the fresh execution.
140
+ ### 7. Overlap Policies & Execution Timeout
141
+ Prevent rogue processes from stacking concurrent duplicate executions:
127
142
 
128
- ### 5. Schedule Expression Syntax
129
- Powered by `croner`, supporting both standard 5-part/6-part cron expressions and user-friendly interval aliases:
143
+ * **Execution timeout (`timeoutSeconds`)** — when the limit is reached, shell subprocesses are killed immediately via the abort signal and agent sessions are disposed so they stop consuming tokens. Default: `1800` (30 minutes).
144
+ * **Overlap policy (`overlapPolicy`)** — controls what happens when a tick fires while the previous run is still active:
145
+ * **`skip`** (default): drops the overlapping run and records a `skipped` entry in the run history.
146
+ * **`queue`**: queues the next execution and starts it as soon as the active job completes.
147
+ * **`replace`**: aborts the active run via `AbortController` and launches a fresh execution.
130
148
 
131
- * `0 9 * * 1-5` — Every weekday at 09:00 AM
132
- * `*/15 * * * *` — Every 15 minutes
133
- * `0 0 * * 0` — Every Sunday at midnight
134
- * `every 10m` / `every 2h` / `every 30s` — Natural duration intervals
135
- * `daily` / `hourly` / `weekly` — Standard predefined shortcuts
149
+ If the daemon was offline at a scheduled time, the run is recorded as `missed` on startup, so gaps in the history stay visible.
136
150
 
137
151
  ---
138
152
 
@@ -150,33 +164,64 @@ Restart your DeepSeek Harness instance and refresh the browser.
150
164
 
151
165
  ## ⚙️ Configuration (`settings.yaml`)
152
166
 
153
- Configuration can be applied in `settings.yaml` or managed interactively via the DSH Settings UI:
167
+ Configuration can be applied in `settings.yaml` or managed interactively via the plugin settings card in DSH:
154
168
 
155
169
  ```yaml
156
170
  # settings.yaml
157
171
  dsh-cron:
158
- storagePath: "data/cron-tasks.json"
159
- maxHistoryEntries: 50
160
- defaultTimezone: "UTC"
161
- defaultModel: ""
162
- notifyOnFailure: true
172
+ botToken: "" # Telegram Bot API token (kept secret; see notes)
173
+ chatId: "" # Telegram chat ID that receives reports
174
+ notifyTelegram: false # deliver reports for every task globally
175
+ onlyOnFailure: false # deliver reports only for failed runs
176
+ kanbanBaseUrl: "http://127.0.0.1:3000" # dsh-kanban HTTP API base URL
163
177
  ```
164
178
 
165
179
  ### Configuration Parameters
166
180
 
167
181
  | Parameter | Type | Default | Description |
168
182
  |:---|:---|:---|:---|
169
- | `storagePath` | `string` | `"data/cron-tasks.json"` | Relative or absolute path where scheduled tasks and run histories are persisted atomically |
170
- | `maxHistoryEntries` | `number` | `50` | Maximum number of run history records preserved per task card |
171
- | `defaultTimezone` | `string` | `"UTC"` | Default IANA timezone used for cron calculations (e.g., `"Europe/Berlin"`, `"America/New_York"`) |
172
- | `defaultModel` | `string` | `""` | Fallback model identifier for tasks created without an explicit model selection |
173
- | `notifyOnFailure` | `boolean` | `true` | Emits a notification badge in the UI if a scheduled background task encounters a failure |
183
+ | `botToken` | `string` | `""` | Telegram Bot API token. If left empty, the plugin tries to inherit the bot configured for `dsh-messenger-gateway` in the DSH settings as a best-effort fallback. Stored as a secret field; the UI only ever displays a masked value |
184
+ | `chatId` | `string` | `""` | Telegram chat ID that receives the reports. Empty value falls back to the first allowed chat of `dsh-messenger-gateway` |
185
+ | `notifyTelegram` | `boolean` | `false` | Global switch: deliver run reports to Telegram |
186
+ | `onlyOnFailure` | `boolean` | `false` | Global switch: deliver reports only for `error`/`timeout` runs |
187
+ | `kanbanBaseUrl` | `string` | `"http://127.0.0.1:3000"` | Base URL of the `dsh-kanban` HTTP API used for automatic card creation |
188
+
189
+ Notes:
190
+
191
+ * Run history is capped at **50 entries per task** (fixed); each entry keeps up to 4000 characters of output.
192
+ * Tasks run in the **server's local timezone**; cron expressions are evaluated by `croner` on the host clock.
193
+ * Tasks persist in the DSH data directory (`cron/tasks.json`) and survive restarts; missed one-shots are detected on startup.
194
+
195
+ ---
196
+
197
+ ## 🔌 HTTP API Reference
198
+
199
+ All endpoints are served by the DSH web server under `/dsh-cron/`. Read endpoints are open to the local UI; **mutating endpoints reject cross-origin requests** and accept bodies up to 1 MB. Creating `script`-type tasks over HTTP additionally requires the `x-dsh-cron-confirm: script` header, which forged cross-site posts cannot attach.
200
+
201
+ | Method | Path | Description |
202
+ |:---|:---|:---|
203
+ | `GET` | `/dsh-cron/tasks` | List tasks; query params `status` (`all/active/paused/completed`), `query` (substring search). Returns tasks, recommendation templates and aggregated stats |
204
+ | `POST` | `/dsh-cron/tasks` | Create or update a task (`id` present → update). Requires `title`, `schedule`, `prompt` |
205
+ | `GET` | `/dsh-cron/tasks/:id/history` | Run history, `?limit=20` |
206
+ | `POST` | `/dsh-cron/tasks/:id/run` | Trigger an immediate manual run |
207
+ | `POST` | `/dsh-cron/tasks/:id/pause` | Pause the schedule |
208
+ | `POST` | `/dsh-cron/tasks/:id/resume` | Resume the schedule |
209
+ | `POST` | `/dsh-cron/tasks/:id/toggle` | Toggle active/paused |
210
+ | `PATCH` | `/dsh-cron/tasks/:id` | Partial update (whitelisted fields only: `title`, `schedule`, `prompt`, `type`, `delivery`, `provider`, `model`, notification/timeout/overlap/kanban settings, `status`, `oneShot`) |
211
+ | `DELETE` | `/dsh-cron/tasks/:id` | Delete the task |
212
+ | `GET` | `/dsh-cron/models` | List LLM providers; `?provider=<id>` lists models |
213
+ | `POST` | `/dsh-cron/chat/start` | Start a "Create with DSH" agent session with the task-setup instructions |
214
+ | `GET` | `/dsh-cron/settings` | Client-safe settings (token masked) |
215
+ | `POST` | `/dsh-cron/settings` | Update integration settings |
216
+ | `POST` | `/dsh-cron/telegram/test` | Send a Telegram test message |
217
+ | `POST` | `/dsh-cron/kanban/test` | Create a Kanban connectivity-test card |
218
+ | `*` | `/dsh-cron/action/:id/:action` | Legacy alias for the task action routes (`run`, `toggle`, `delete`, `history`) |
174
219
 
175
220
  ---
176
221
 
177
222
  ## 🧪 Testing
178
223
 
179
- Run the automated test suite covering schedulers, atomic storage, and HTTP handlers:
224
+ Run the automated test suite covering schedule parsing, the scheduler engine, atomic storage, HTTP helpers, notifications and tool contracts:
180
225
 
181
226
  ```bash
182
227
  npm test
@@ -187,13 +232,3 @@ npm test
187
232
  ## 📄 License
188
233
 
189
234
  MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
190
-
191
- ### Kanban & Token Cost Integration (v0.1.17)
192
- - **Automatic Kanban Card Creation**: Automatically creates task/bug cards in `dsh-kanban` on task failure (`on_failure`) or every run (`always`).
193
- - **Token & Execution Cost Meter**: Tracks token consumption (input, output, cache tokens) for LLM executions and estimates USD expenses using current model pricing.
194
- - **Aggregated Analytics Bar**: Live dashboard displaying active jobs count, total executions, total token consumption, and aggregate estimated dollar spend.
195
-
196
- ### One-Shot Delayed Tasks (v0.1.18)
197
- - **Precise Timing & Relative Delays**: Supports one-time tasks triggered at exact ISO 8601 timestamps (`at: 2026-09-05T12:00:00Z`) or human-friendly relative delays (`in 20m`, `in 2h`, `через 15 минут`).
198
- - **Auto-Completion Lifecycle**: One-shot jobs transition automatically to `completed` status after their single run, preventing unexpected repeats.
199
- - **Dedicated Filter**: View historical and pending one-shot executions under the «Completed» (`completed`) tab.