@goodandready/dsh-cron 0.2.5 → 0.2.7

package/README.md

@@ -99,13 +99,15 @@ Autonomous agents can manage schedules directly:
 
 | Tool | Description |
 |:---|:---|
-| `cron_create_task` | Creates a scheduled task: `title`, `schedule`, `prompt`, optional `type` (`llm`/`script`/`node`/`python`/`http`/`ssh`/`docker`/`skill`/`workflow`), `delivery`, `provider`, `model`, `channels`, `template`, `notifyTelegram`, `onlyOnFailure`, `timeoutSeconds`, `overlapPolicy`, `kanbanMode` |
+| `cron_create_task` | Creates a scheduled task: `title`, `schedule`, `prompt`, `fallbackModel` (one retry on a stronger model when a run fails), optional `type` (`llm`/`script`/`node`/`python`/`http`/`ssh`/`docker`/`skill`/`workflow`), `delivery`, `provider`, `model`, `channels`, `template`, `notifyTelegram`, `onlyOnFailure`, `timeoutSeconds`, `overlapPolicy`, `kanbanMode` |
 | `cron_schedule_task` | Alias of `cron_create_task` kept for compatibility with existing agent prompts |
 | `cron_list_tasks` | Lists tasks with statuses, next run timestamps, token totals, and cost estimates |
 | `cron_pause_task` | Pauses a schedule without deleting its configuration |
 | `cron_resume_task` | Resumes a paused schedule |
 | `cron_delete_task` | Permanently removes a task and its history |
 | `cron_run_task` | Triggers an immediate out-of-band run |
+| `cron_get_task` | Reads the full configuration of one task, including fields the list does not show |
+| `cron_update_task` | Changes an existing task in place (whitelisted fields, same validation as the HTTP route); the model is told to confirm code-executing changes with the user first |
 
 Example invocation the model can make during a conversation:
 
@@ -147,12 +149,21 @@ Every task picks its own runtime; non-LLM runtimes need no model and consume no
 * **Environment variables** — a per-task `env` map (KEY VALUE per line in the UI) applied to external runtimes; secrets do not belong here.
 * **Workspaces and worktrees** — bind a task to a harness workspace (`workspaceId`) and, for code-modifying agent tasks, run it in an isolated git worktree (`worktree`, `keepWorktree`).
 
-### 7. Session Integration & Permissions
+### 7. Cost Control: Fallback Model
+A task can run on the cheap model by default and still finish on the strong one: set `fallbackModel` (and optionally `fallbackProvider`) and a failed run — `error` or `timeout` — is retried **once** on that model before the ordinary retry backoff applies. History records which model produced the result and whether the fallback was used, usage and cost of both attempts are summed, and the `{model}` template variable renders the model that finished the run. Only agent-mediated tasks (`llm`, `skill`, `workflow`) can use a fallback.
+
+### 8. Session Integration & Permissions
 * **Per-task permission presets** — `default`, `read-only`, `workspace-write`, or `full` are applied to the task's agent session before the prompt runs.
 * **Session auto-archive** — isolated cron sessions are archived after each run (best-effort) so they do not clutter the chat list.
 * **History → session navigation** — every LLM run records its session; open it straight from the run history entry.
 
-### 8. Notification Channels & Message Templates
+### 9. Quiet by Rule
+A task with output can carry a **silent rule** written in plain words ("stay silent when no filesystem is above 80%"). On a successful run a cheap model judges the output against that rule and the report is skipped when the verdict is to stay silent, with the reason recorded in the run history. It fails open: no rule, no model, a failed call or an unreadable answer all mean the report is delivered. `silentRuleModel` (plugin setting) picks the model used for the judgement.
+
+### 10. Failure Diagnosis
+Agent tasks can ask for a diagnosis: with `inspectOnFailure` set, a failed run (`error` or `timeout`) is read by a model together with the task prompt and truncated output, and the run history stores a short diagnosis plus a concrete prompt change. The history entry offers to load that suggestion into the edit form — nothing is applied automatically. The model is configurable with `inspectorModel`, and `{diagnosis}` is available in message templates. A broken or unavailable model call leaves the failed run exactly as it was.
+
+### 11. Notification Channels & Message Templates
 A finished run is delivered to every channel configured for the task — Telegram, dsh-kanban, Discord, Slack, ntfy, Bark, PushPlus, voice via `dsh-tts`, and Gitea issues:
 
 * **Per-task channels** — tick the channels in the task form; an explicit selection overrides the legacy `notifyTelegram` / `kanbanMode` switches, and an empty selection falls back to them.
@@ -168,11 +179,11 @@ A finished run is delivered to every channel configured for the task — Telegra
 * **Gitea** — opens an issue with the run report (`giteaBaseUrl`, `giteaRepo`, token credential); failures are labelled `cron`, `bug`, `alert`.
 * **Test dispatch button** — verify Telegram connectivity on the spot before scheduling critical jobs.
 
-### 9. Kanban Integration & Cost Meter
+### 12. Kanban Integration & Cost Meter
 * **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).
 * **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.
 
-### 10. Overlap Policies & Execution Timeout
+### 13. Overlap Policies & Execution Timeout
 Prevent rogue processes from stacking concurrent duplicate executions:
 
 * **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).
@@ -183,10 +194,129 @@ Prevent rogue processes from stacking concurrent duplicate executions:
 
 If the daemon was offline at a scheduled time, the run is recorded as `missed` on startup, so gaps in the history stay visible.
 
-### 11. Heartbeat Monitoring (#16-style dead man's switch)
+### 14. Heartbeat Monitoring (#16-style dead man's switch)
 * Set `heartbeatUrl` and `heartbeatIntervalSec` in the plugin settings and the scheduler pings that URL on schedule — an external monitor alerts when the pings stop.
 * A built-in `GET /dsh-cron/heartbeat` endpoint reports liveness, active task count and the last run time for your own watchdogs.
 
+### 15. Declarative Jobs From the Profile Config (#50)
+Long-lived operational jobs can be declared in the profile configuration instead of being recreated by hand in the UI. The config file owns the jobs it declares: at every plugin start they are created or updated, and a job that disappears from the file is removed.
+
+Add a `jobs` list to the plugin section of your profile config (`cordis.patch.yml`):
+
+```yaml
+dsh-cron:
+  jobs:
+    - id: nightly-backup
+      title: Nightly backup
+      schedule: "0 3 * * *"
+      type: script
+      prompt: "bash /path/to/backup.sh"
+      channels: ["telegram"]
+      timeoutSeconds: 3600
+    - id: morning-digest
+      title: Morning digest
+      schedule: "0 8 * * 1-5"
+      type: llm
+      prompt: "Prepare a brief morning digest of active tasks."
+      provider: my-provider
+      model: provider-id/model-id
+```
+
+* Required per entry: `id`, `title`, `schedule`; the types that carry their payload in the prompt (`script`, `node`, `python`, `ssh`, `docker`, `llm`, `skill`, `workflow`) also need a non-empty `prompt`. `http` is exempt: its target is given by `httpUrl` (or `prompt`).
+* Any other task field is passed through with the same validation as the API: `channels`, `model`, `provider`, `fallbackModel`, `silentRule`, `inspectOnFailure`, `timezone`, `timeoutSeconds`, `template`, `env`, `cwd`, and the runtime fields (`nodePath`, `pythonPath`, `httpUrl`, `httpMethod`, `httpHeaders`, `httpBody`, `sshProfileId`, `sshTarget`, `dockerImage`, `workspaceId`, `worktree`, `keepWorktree`, `skillName`, `workflowName`).
+* Declared jobs are marked **managed by the config**; the panel shows a source label instead of edit and delete actions.
+* Editing, pausing, resuming, toggling or deleting a config-owned task is refused with `409` on the panel and on the API, and a create-or-update `POST /dsh-cron/tasks` that carries the existing `id` of a config-owned task is refused the same way — the config file is the source of truth. **Run Now** stays available.
+* A task with the same `id` created through the UI, the API or an agent tool is never overwritten: the entry is skipped and the conflict is written to the log.
+* Code-executing types are activated like any other declared job, but at startup the plugin writes a warning to the log, so a code path introduced through the config file is visible.
+* Entries are validated one by one with an indexed message (`config.jobs[i]: …`); a broken entry is skipped and cannot stop the remaining jobs or the profile.
+
+### 16. External REST API (`/dsh-cron/api/*`, #54)
+External systems (CI, host cron, `curl`) can drive the scheduler without opening the browser panel. This is the only surface behind a bearer token; the panel routes stay local and cross-origin-protected.
+
+Set the token as the plugin setting `apiToken` (masked like every secret). Auth and errors:
+* no token configured → the whole surface answers `503`;
+* a missing or wrong `Authorization: Bearer <token>` → `401`, compared in constant time.
+
+| Method | Path | Description |
+|:---|:---|:---|
+| `GET` | `/dsh-cron/api/tasks` | List tasks (`status` / `query` filters as the panel) |
+| `GET` | `/dsh-cron/api/tasks/:id` | Read one task |
+| `POST` | `/dsh-cron/api/tasks` | Create a task, or update the existing one when `id` is present |
+| `DELETE` | `/dsh-cron/api/tasks/:id` | Delete a task |
+| `POST` | `/dsh-cron/api/tasks/:id/run` | Force an immediate run |
+
+The operations reuse the panel handlers, so the `x-dsh-cron-confirm: script` gate for code-executing types and the `409` refusals for config-owned tasks behave exactly as in the UI.
+
+```bash
+BASE="http://127.0.0.1:3080"
+TOKEN="<API_TOKEN>"
+
+# list
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks"
+
+# create, or update when the body carries the id
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"id":"cleanup","title":"Cleanup","schedule":"0 4 * * *","prompt":"Remove stale temporary files."}' \
+  "$BASE/dsh-cron/api/tasks"
+
+# force a run
+curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks/cleanup/run"
+
+# delete
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks/cleanup"
+
+# a code-executing task also needs the confirmation header
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "x-dsh-cron-confirm: script" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Disk check","schedule":"0 * * * *","type":"script","prompt":"df -h"}' \
+  "$BASE/dsh-cron/api/tasks"
+```
+
+### 17. Prometheus Metrics (#53)
+`GET /dsh-cron/metrics` returns Prometheus text exposition, so the scheduler can be scraped without any extra dependency:
+
+* `dsh_cron_tasks_total{status}` — tasks by status (gauge).
+* `dsh_cron_task_last_duration_seconds{task}` — duration of a task's last finished run, in seconds (gauge).
+* `dsh_cron_runs_total{status}` — finished runs since the plugin process started (counter); the statuses are `success`, `error`, `timeout`, `skipped` and `missed`.
+* `dsh_cron_run_records` — run records currently kept in memory (gauge).
+
+Only counts, statuses and durations are exported; prompts, run output and task configuration never appear in the exposition.
+
+```yaml
+scrape_configs:
+  - job_name: dsh-cron
+    static_configs:
+      - targets: ["127.0.0.1:3080"]
+    metrics_path: /dsh-cron/metrics
+```
+
+### 18. Strict Channel Validation (#121)
+Creating or updating a task with an unknown delivery-channel id is now rejected with `400`, and the offending ids are listed:
+
+```json
+{ "ok": false, "error": "Unknown channel ids: email_ping", "unknownChannels": ["email_ping"] }
+```
+
+Changed in v0.2.7: previously an unknown id was silently dropped, so a client with a typo received `ok: true` and ended up with a task that delivered nowhere.
+
+Import deliberately stays tolerant (a file may come from an older build): unknown ids are dropped from the imported task, but they are named in the response (`unknownChannels`) and written to the scheduler log instead of disappearing silently.
+
+### 19. Post-Install Verification (#126)
+`deploy.sh` has a verify-only mode that inspects an already installed profile without installing anything:
+
+```bash
+bash deploy.sh verify [exact-version]
+```
+
+It checks that the profile reports the requested version (default: the `package.json` version), authenticates to the web UI, then downloads the client bundle and confirms the package name is present.
+
+Why it is needed: the web profile can sit behind an authentication plugin and answer `401` to an anonymous request, and a plugin client bundle is served only through the exact combined `??` URL printed in the authenticated index — a bare `/plugins/<name>/client.js` answers `404`. The check therefore builds an authenticated session first.
+
+Environment used by the check: `DSH_WEB_BASE` (default `http://127.0.0.1:3080`), `DSH_WEB_TOKEN` (the token; when unset, the script reads the last one printed to the unit journal), `DSH_WEB_UNIT` (default `dsh-web.service`). No secret is stored in the script.
+
+### 20. Internal Refactor: Schedule Parsing and Arming (#97)
+Developer-facing, no behaviour change. `parseScheduleExpression` was split into small functions that keep the same branch order — `parseAtExpression`, `parseRelativeOneShot`, `parseIntervalExpression`, `parseAliasExpression`, `parseCronExpression` — and `scheduleTask` into `clearScheduled`, `scheduleOneShot` and `scheduleCron`. The existing test suite passed unchanged and targeted tests were added for branch precedence and error messages.
+
 ---
 
 ## 📦 Installation
@@ -235,6 +365,8 @@ dsh-cron:
   giteaBaseUrl: ""             # giteaRepo = owner/repo, giteaTokenRef = credential NAME
   giteaRepo: ""
   giteaTokenRef: ""
+  # --- external REST API (#54) ---
+  apiToken: ""                 # bearer token for the external /dsh-cron/api/* surface (masked; empty = 503)
 ```
 
 ### Configuration Parameters
@@ -260,6 +392,7 @@ dsh-cron:
 | `pushplusUrl` / `pushplusTokenRef` | `string` | `"https://www.pushplus.plus/send"` / `""` | PushPlus endpoint (override for a self-hosted proxy) and token credential name |
 | `ttsBaseUrl` | `string` | `"http://127.0.0.1:3080"` | Base URL of the `dsh-tts` plugin used for voice announcements |
 | `giteaBaseUrl` / `giteaRepo` / `giteaTokenRef` | `string` | `""` | Gitea channel: base URL, `owner/repo`, and the credential name of the API token |
+| `apiToken` | `string` | `""` | Bearer token for the external `/dsh-cron/api/*` surface. Stored as a secret field and returned masked; empty disables the surface (503), a wrong value answers 401 |
 
 Notes:
 
@@ -283,6 +416,7 @@ All endpoints are served by the DSH web server under `/dsh-cron/`. Read endpoint
 | `POST` | `/dsh-cron/tasks/:id/resume` | Resume the schedule |
 | `POST` | `/dsh-cron/tasks/:id/toggle` | Toggle active/paused |
 | `POST` | `/dsh-cron/tasks/:id/duplicate` | Creates a paused copy of a task: configuration copied, run state (history, counters, last run) reset |
+| `GET` | `/dsh-cron/recipes` | Built-in recipe catalog: ready-to-use monitoring presets grouped by category, all read-only |
 | `GET` | `/dsh-cron/tasks/export` | Versioned JSON document with task configuration only — no history or counters. Channels reference credentials by name, but a task-level `env` map or HTTP headers you typed in yourself are part of the configuration and therefore appear in the file |
 | `POST` | `/dsh-cron/tasks/import` | Validates a document and applies it with `add`, `replace` or `skip`; supports a `dryRun` summary. Imported tasks always start **paused**, so a restore never fires until reviewed |
 | `PATCH` | `/dsh-cron/tasks/:id` | Partial update (whitelisted fields only: `title`, `schedule`, `prompt`, `type`, `delivery`, `provider`, `model`, runtime settings, `channels`, `template`, notification/timeout/overlap/kanban settings, `status`, `oneShot`) |
@@ -295,6 +429,10 @@ All endpoints are served by the DSH web server under `/dsh-cron/`. Read endpoint
 | `POST` | `/dsh-cron/telegram/test` | Send a Telegram test message |
 | `POST` | `/dsh-cron/kanban/test` | Create a Kanban connectivity-test card |
 | `*` | `/dsh-cron/action/:id/:action` | Legacy alias for the task action routes (`run`, `toggle`, `delete`, `history`) |
+| `GET` | `/dsh-cron/metrics` | Prometheus text exposition of task and run counters — never prompts or output (#53) |
+| `GET` / `POST` | `/dsh-cron/api/tasks` | External token-guarded surface: list / create-or-update (#54) |
+| `GET` / `DELETE` | `/dsh-cron/api/tasks/:id` | External token-guarded surface: read / delete (#54) |
+| `POST` | `/dsh-cron/api/tasks/:id/run` | External token-guarded surface: force a run (#54) |
 
 ---
 

package/docs/README.ru.md

@@ -98,13 +98,15 @@ graph TD
 
 | Инструмент | Описание |
 |:---|:---|
-| `cron_create_task` | Создаёт задачу: `title`, `schedule`, `prompt`, опционально `type` (`llm`/`script`/`node`/`python`/`http`/`ssh`/`docker`/`skill`/`workflow`), `delivery`, `provider`, `model`, `channels`, `template`, `notifyTelegram`, `onlyOnFailure`, `timeoutSeconds`, `overlapPolicy`, `kanbanMode` |
+| `cron_create_task` | Создаёт задачу: `title`, `schedule`, `prompt`, `fallbackModel` (одна повторная попытка на сильной модели при сбое), опционально `type` (`llm`/`script`/`node`/`python`/`http`/`ssh`/`docker`/`skill`/`workflow`), `delivery`, `provider`, `model`, `channels`, `template`, `notifyTelegram`, `onlyOnFailure`, `timeoutSeconds`, `overlapPolicy`, `kanbanMode` |
 | `cron_schedule_task` | Псевдоним `cron_create_task` для совместимости с существующими промптами |
 | `cron_list_tasks` | Список задач со статусами, временем следующего запуска, токенами и стоимостью |
 | `cron_pause_task` | Приостанавливает расписание без удаления конфигурации |
 | `cron_resume_task` | Возобновляет приостановленное расписание |
 | `cron_delete_task` | Полностью удаляет задачу и её историю |
 | `cron_run_task` | Немедленный внеплановый запуск |
+| `cron_get_task` | Полная конфигурация одной задачи, включая поля, которых нет в списке |
+| `cron_update_task` | Изменяет существующую задачу на месте (whitelisted-поля, та же валидация, что у HTTP-маршрута); модели предписано сперва подтверждать с пользователем изменения, исполняющие код |
 
 Пример вызова модели в диалоге:
 
@@ -146,12 +148,21 @@ cron_create_task({
 * **Переменные окружения** — карта `env` на задачу (в UI — строки KEY VALUE) для внешних рантаймов; секретам здесь не место.
 * **Workspace и worktree** — привязка задачи к workspace харнесса (`workspaceId`) и, для изменяющих код агентских задач, запуск в изолированном git worktree (`worktree`, `keepWorktree`).
 
-### 7. Интеграция сессий и права
+### 7. Экономия: fallback-модель
+Задача может идти на дешёвой модели по умолчанию и всё же завершиться на сильной: задайте `fallbackModel` (и при необходимости `fallbackProvider`), и сбойный запуск (`error` или `timeout`) один раз повторится на этой модели, прежде чем включится обычный retry с задержкой. В истории видно, какая модель произвела результат и был ли использован fallback; расход и стоимость обеих попыток суммируются; переменная шаблона `{model}` подставляет модель, завершившую запуск. Fallback доступен только агентским типам (`llm`, `skill`, `workflow`).
+
+### 8. Интеграция сессий и права
 * **Permission-пресеты на задачу** — `default`, `read-only`, `workspace-write` или `full` применяются к сессии агента перед запуском промпта.
 * **Автоархивация сессий** — изолированные cron-сессии архивируются после запуска (best-effort), не засоряя список чатов.
 * **История → сессия** — каждый LLM-запуск хранит свою сессию; открыть диалог можно прямо из записи истории.
 
-### 8. Каналы доставки и шаблоны сообщений
+### 9. Тишина по правилу
+У задачи с выводом может быть **правило тишины**, написанное словами («молчи, если ни один раздел не занят больше 80%»). На успешном запуске дешёвая модель сверяет вывод с правилом, и отчёт пропускается, если вердикт — молчать; причина сохраняется в истории запуска. Работает fail-open: нет правила, нет модели, сбой вызова или нечитаемый ответ — отчёт доставляется. Настройка `silentRuleModel` задаёт модель для проверки.
+
+### 10. Диагностика сбоев
+Агентские задачи могут заказывать диагноз: с включённым `inspectOnFailure` сбойный запуск (`error` или `timeout`) вместе с промптом задачи и обрезанным выводом читает модель, и в историю запуска попадают короткий диагноз и конкретная правка промпта. В записи истории есть кнопка, подставляющая эту правку в форму редактирования — автоматически ничего не применяется. Модель задаётся настройкой `inspectorModel`, в шаблонах доступна переменная `{diagnosis}`. Недоступная модель оставляет сбойный запуск ровно таким, каким он был.
+
+### 11. Каналы доставки и шаблоны сообщений
 Отчёт о завершённом запуске уходит во все каналы, выбранные для задачи — Telegram, dsh-kanban, Discord, Slack, ntfy, Bark, PushPlus, голос через `dsh-tts` и issue в Gitea:
 
 * **Перенос задач** — экспорт всей конфигурации в версионированный JSON и импорт с предварительной сводкой; импортированные задачи приходят на паузе.
@@ -168,11 +179,11 @@ cron_create_task({
 * **Gitea** — создаёт issue с отчётом (`giteaBaseUrl`, `giteaRepo`, credential токена); сбойные запуски помечаются метками `cron`, `bug`, `alert`.
 * **Кнопка проверки** — проверьте доставку в Telegram до запуска критичных задач.
 
-### 9. Интеграция с Kanban и учёт стоимости
+### 12. Интеграция с Kanban и учёт стоимости
 * **Автоматические карточки Kanban** — при `kanbanMode` = `on_failure` или `always` плагин создаёт карточки в `dsh-kanban` (`on_failure` → *Backlog* при `error`/`timeout`; `always` → *Done*/*Backlog* по завершении).
 * **Счётчик токенов и стоимости** — потребление токенов (ввод, вывод, чтения из кэша) учитывается по запускам и задачам с оценкой в USD по встроенной таблице цен и сводной панелью аналитики.
 
-### 10. Политики наложения и таймаут выполнения
+### 13. Политики наложения и таймаут выполнения
 
 * **Таймаут (`timeoutSeconds`)** — по достижении лимита shell-процесс немедленно завершается через abort-сигнал, а агентская сессия закрывается, чтобы не расходовать токены. По умолчанию `1800` (30 минут).
 * **Политика наложения (`overlapPolicy`)** — что делать, когда тик срабатывает при ещё активном предыдущем запуске:
@@ -228,8 +239,133 @@ dsh-cron:
   giteaBaseUrl: ""             # giteaRepo = owner/repo, giteaTokenRef = ИМЯ credential
   giteaRepo: ""
   giteaTokenRef: ""
+  # --- внешний REST API (#54) ---
+  apiToken: ""                 # bearer-токен внешнего префикса /dsh-cron/api/* (маскируется; пусто = 503)
+```
+
+### 14. Мониторинг heartbeat (dead man's switch)
+* Задайте `heartbeatUrl` и `heartbeatIntervalSec` в настройках плагина — планировщик будет пинговать этот адрес по расписанию, и внешний монитор сообщит, когда пинги прекратятся.
+* Встроенный эндпоинт `GET /dsh-cron/heartbeat` сообщает живость, число активных задач и время последнего запуска для ваших собственных сторожей.
+
+### 15. Задачи из конфига профиля (#50)
+Долгоживущие эксплуатационные задачи можно объявлять в конфиге профиля, а не пересоздавать руками в интерфейсе. Владелец объявленных задач — файл конфига: при каждом старте плагина они создаются или обновляются, а задача, исчезнувшая из файла, удаляется.
+
+Добавьте список `jobs` в секцию плагина конфига профиля (`cordis.patch.yml`):
+
+```yaml
+dsh-cron:
+  jobs:
+    - id: nightly-backup
+      title: Nightly backup
+      schedule: "0 3 * * *"
+      type: script
+      prompt: "bash /path/to/backup.sh"
+      channels: ["telegram"]
+      timeoutSeconds: 3600
+    - id: morning-digest
+      title: Morning digest
+      schedule: "0 8 * * 1-5"
+      type: llm
+      prompt: "Prepare a brief morning digest of active tasks."
+      provider: my-provider
+      model: provider-id/model-id
+```
+
+* Обязательные поля записи: `id`, `title`, `schedule`; типам, у которых полезная нагрузка — это промпт (`script`, `node`, `python`, `ssh`, `docker`, `llm`, `skill`, `workflow`), нужен ещё непустой `prompt`. `http` — исключение: цель задаётся `httpUrl` (или `prompt`).
+* Остальные поля задачи проходят как есть с той же валидацией, что и в API: `channels`, `model`, `provider`, `fallbackModel`, `silentRule`, `inspectOnFailure`, `timezone`, `timeoutSeconds`, `template`, `env`, `cwd` и рантайм-поля (`nodePath`, `pythonPath`, `httpUrl`, `httpMethod`, `httpHeaders`, `httpBody`, `sshProfileId`, `sshTarget`, `dockerImage`, `workspaceId`, `worktree`, `keepWorktree`, `skillName`, `workflowName`).
+* Объявленные задачи помечаются как **управляемые конфигом**; в панели вместо действий правки и удаления выводится метка источника.
+* Правка, пауза, возобновление, переключение и удаление конфиг-задачи отклоняются с `409` в панели и по API, и создание-обновление через `POST /dsh-cron/tasks` с существующим `id` конфиг-задачи отклоняется так же — источник правды файл конфига. **Запустить сейчас** остаётся доступным.
+* Задача с тем же `id`, созданная через UI, API или инструмент агента, никогда не перезаписывается: запись пропускается, конфликт пишется в лог.
+* Код-исполняющие типы активируются как обычные объявленные задачи, но при старте плагин пишет предупреждение в лог — путь исполнения кода, добавленный правкой конфига, остаётся видимым.
+* Записи валидируются по одной с указанием индекса (`config.jobs[i]: …`); одна плохая запись пропускается и не может остановить остальные задачи или профиль.
+
+### 16. Внешний REST API (`/dsh-cron/api/*`, #54)
+Внешние системы (CI, cron хоста, `curl`) могут управлять планировщиком без открытия панели. Это единственная поверхность за bearer-токеном; маршруты панели остаются локальными и защищёнными от cross-origin.
+
+Токен задаётся настройкой плагина `apiToken` (маскируется, как любой секрет). Аутентификация и ошибки:
+* токен не задан → вся поверхность отвечает `503`;
+* нет заголовка `Authorization: Bearer <token>` или токен неверный → `401`; сравнение постоянное по времени.
+
+| Метод | Путь | Описание |
+|:---|:---|:---|
+| `GET` | `/dsh-cron/api/tasks` | Список задач (фильтры `status` / `query`, как в панели) |
+| `GET` | `/dsh-cron/api/tasks/:id` | Чтение одной задачи |
+| `POST` | `/dsh-cron/api/tasks` | Создание задачи или обновление существующей при наличии `id` |
+| `DELETE` | `/dsh-cron/api/tasks/:id` | Удаление задачи |
+| `POST` | `/dsh-cron/api/tasks/:id/run` | Принудительный немедленный запуск |
+
+Операции переиспользуют обработчики панели, поэтому гейт `x-dsh-cron-confirm: script` для код-исполняющих типов и отказ `409` для конфиг-задач действуют здесь так же, как в UI.
+
+```bash
+BASE="http://127.0.0.1:3080"
+TOKEN="<API_TOKEN>"
+
+# список
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks"
+
+# создание или обновление, если в теле есть id
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"id":"cleanup","title":"Cleanup","schedule":"0 4 * * *","prompt":"Remove stale temporary files."}' \
+  "$BASE/dsh-cron/api/tasks"
+
+# принудительный запуск
+curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks/cleanup/run"
+
+# удаление
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks/cleanup"
+
+# код-исполняющей задаче нужен ещё заголовок подтверждения
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "x-dsh-cron-confirm: script" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Disk check","schedule":"0 * * * *","type":"script","prompt":"df -h"}' \
+  "$BASE/dsh-cron/api/tasks"
+```
+
+### 17. Метрики Prometheus (#53)
+`GET /dsh-cron/metrics` отдаёт текст в формате Prometheus, поэтому планировщик можно снимать scrape'ом без новых зависимостей:
+
+* `dsh_cron_tasks_total{status}` — число задач по статусам (gauge).
+* `dsh_cron_task_last_duration_seconds{task}` — длительность последнего завершённого запуска задачи в секундах (gauge).
+* `dsh_cron_runs_total{status}` — завершённые запуски с момента старта процесса плагина (counter); статусы `success`, `error`, `timeout`, `skipped`, `missed`.
+* `dsh_cron_run_records` — число записей о запусках, хранимых в памяти (gauge).
+
+В экспозицию попадают только счётчики, статусы и длительности; промпты, вывод запусков и конфигурация задач в неё не входят.
+
+```yaml
+scrape_configs:
+  - job_name: dsh-cron
+    static_configs:
+      - targets: ["127.0.0.1:3080"]
+    metrics_path: /dsh-cron/metrics
+```
+
+### 18. Строгая проверка каналов (#121)
+Создание или обновление задачи с неизвестным идентификатором канала теперь отклоняется с `400`, а виновники перечисляются в ответе:
+
+```json
+{ "ok": false, "error": "Unknown channel ids: email_ping", "unknownChannels": ["email_ping"] }
 ```
 
+Changed in v0.2.7: раньше неизвестный идентификатор молча отбрасывался, поэтому клиент с опечаткой получал `ok: true` и задачу, которая никуда не доставляет.
+
+Импорт намеренно остаётся терпимым (файл может быть из старой версии): неизвестные идентификаторы отбрасываются у импортируемой задачи, но перечисляются в ответе (`unknownChannels`) и пишутся в лог планировщика, а не исчезают молча.
+
+### 19. Проверка после установки (#126)
+У `deploy.sh` есть режим только-проверки уже установленного профиля, ничего не устанавливающий:
+
+```bash
+bash deploy.sh verify [exact-version]
+```
+
+Он проверяет, что профиль сообщает нужную версию (по умолчанию — версия из `package.json`), аутентифицируется в web UI, затем скачивает клиентский бандл и убеждается, что имя пакета в нём присутствует.
+
+Зачем это нужно: web-профиль может стоять за плагином аутентификации и отвечать `401` на анонимный запрос, а клиентский бандл плагина отдаётся только по точному combined-URL вида `??` из аутентифицированного индекса — голый `/plugins/<name>/client.js` отвечает `404`. Поэтому проверка сначала строит аутентифицированную сессию.
+
+Переменные окружения проверки: `DSH_WEB_BASE` (по умолчанию `http://127.0.0.1:3080`), `DSH_WEB_TOKEN` (токен; если не задан, скрипт берёт последний из журнала юнита), `DSH_WEB_UNIT` (по умолчанию `dsh-web.service`). Секретов в скрипте нет.
+
+### 20. Внутренняя разбивка: разбор расписания и постановка (#97)
+Только для разработчиков, поведение не меняется. `parseScheduleExpression` разбит на маленькие функции с тем же порядком ветвей — `parseAtExpression`, `parseRelativeOneShot`, `parseIntervalExpression`, `parseAliasExpression`, `parseCronExpression`, — а `scheduleTask` — на `clearScheduled`, `scheduleOneShot` и `scheduleCron`. Прежний набор тестов прошёл без правок, добавлены точечные тесты на приоритет ветвей и ошибки.
+
 ### Параметры
 
 | Параметр | Тип | По умолчанию | Описание |
@@ -253,6 +389,7 @@ dsh-cron:
 | `pushplusUrl` / `pushplusTokenRef` | `string` | `"https://www.pushplus.plus/send"` / `""` | Endpoint PushPlus (переопределяется для self-hosted прокси) и имя credential токена |
 | `ttsBaseUrl` | `string` | `"http://127.0.0.1:3080"` | Базовый URL плагина `dsh-tts` для голосовых объявлений |
 | `giteaBaseUrl` / `giteaRepo` / `giteaTokenRef` | `string` | `""` | Канал Gitea: базовый URL, `owner/repo` и имя credential API-токена |
+| `apiToken` | `string` | `""` | Bearer-токен внешней поверхности `/dsh-cron/api/*`. Секретное поле, отдаётся замаскированным; пусто отключает поверхность (503), неверное значение — 401 |
 
 Примечания:
 
@@ -276,6 +413,7 @@ dsh-cron:
 | `POST` | `/dsh-cron/tasks/:id/resume` | Возобновление расписания |
 | `POST` | `/dsh-cron/tasks/:id/toggle` | Переключение активна/на паузе |
 | `POST` | `/dsh-cron/tasks/:id/duplicate` | Копия задачи в статусе «на паузе»: настройки копируются, история и счётчики сбрасываются |
+| `GET` | `/dsh-cron/recipes` | Встроенный каталог рецептов: готовые мониторинговые пресеты по категориям, все только на чтение |
 | `GET` | `/dsh-cron/tasks/export` | Версионированный JSON только с конфигурацией задач — без истории и счётчиков. Каналы ссылаются на credential по имени, но введённые вручную `env` и HTTP-заголовки задачи являются частью конфигурации и попадают в файл |
 | `POST` | `/dsh-cron/tasks/import` | Проверяет документ и применяет его стратегией `add`, `replace` или `skip`; поддерживает `dryRun`. Импортированные задачи всегда приходят **на паузе** — восстановление не сработает само |
 | `PATCH` | `/dsh-cron/tasks/:id` | Частичное обновление (только whitelisted-поля: `title`, `schedule`, `prompt`, `type`, `delivery`, `provider`, `model`, настройки уведомлений/таймаута/overlap/kanban, `status`, `oneShot`) |
@@ -288,6 +426,10 @@ dsh-cron:
 | `POST` | `/dsh-cron/telegram/test` | Тестовое сообщение в Telegram |
 | `POST` | `/dsh-cron/kanban/test` | Тестовая карточка в Kanban |
 | `*` | `/dsh-cron/action/:id/:action` | Legacy-алиас действий над задачей (`run`, `toggle`, `delete`, `history`) |
+| `GET` | `/dsh-cron/metrics` | Текст в формате Prometheus: счётчики задач и запусков — без промптов и вывода (#53) |
+| `GET` / `POST` | `/dsh-cron/api/tasks` | Внешняя поверхность под токеном: список / создание-обновление (#54) |
+| `GET` / `DELETE` | `/dsh-cron/api/tasks/:id` | Внешняя поверхность под токеном: чтение / удаление (#54) |
+| `POST` | `/dsh-cron/api/tasks/:id/run` | Внешняя поверхность под токеном: принудительный запуск (#54) |
 
 ---