opencode-windows-scheduler 1.1.0 → 1.2.1

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 (144) hide show
  1. package/CHANGELOG.md +60 -1
  2. package/README.md +18 -8
  3. package/README.ru.md +13 -3
  4. package/ROADMAP-STRATEGY.md +2 -2
  5. package/ROADMAP.md +51 -18
  6. package/dist/core/analytics.d.ts +10 -0
  7. package/dist/core/analytics.d.ts.map +1 -1
  8. package/dist/core/analytics.js +21 -0
  9. package/dist/core/dry-run.d.ts +18 -1
  10. package/dist/core/dry-run.d.ts.map +1 -1
  11. package/dist/core/dry-run.js +49 -3
  12. package/dist/core/matrix.d.ts.map +1 -1
  13. package/dist/core/matrix.js +10 -0
  14. package/dist/core/one-shot.d.ts +62 -0
  15. package/dist/core/one-shot.d.ts.map +1 -0
  16. package/dist/core/one-shot.js +126 -0
  17. package/dist/core/otel.d.ts +4 -0
  18. package/dist/core/otel.d.ts.map +1 -0
  19. package/dist/core/otel.js +98 -0
  20. package/dist/core/prometheus.d.ts +23 -0
  21. package/dist/core/prometheus.d.ts.map +1 -0
  22. package/dist/core/prometheus.js +146 -0
  23. package/dist/core/ps-wrapper.d.ts +36 -2
  24. package/dist/core/ps-wrapper.d.ts.map +1 -1
  25. package/dist/core/ps-wrapper.js +124 -4
  26. package/dist/core/record-history.d.ts.map +1 -1
  27. package/dist/core/record-history.js +9 -0
  28. package/dist/core/schedule-gate.d.ts +2 -0
  29. package/dist/core/schedule-gate.d.ts.map +1 -0
  30. package/dist/core/schedule-gate.js +182 -0
  31. package/dist/core/schedule-v2.d.ts +88 -0
  32. package/dist/core/schedule-v2.d.ts.map +1 -0
  33. package/dist/core/schedule-v2.js +496 -0
  34. package/dist/core/scheduler/linux.d.ts +12 -3
  35. package/dist/core/scheduler/linux.d.ts.map +1 -1
  36. package/dist/core/scheduler/linux.js +80 -3
  37. package/dist/core/scheduler/mac.d.ts.map +1 -1
  38. package/dist/core/scheduler/mac.js +17 -3
  39. package/dist/core/scheduler/posix.d.ts.map +1 -1
  40. package/dist/core/scheduler/posix.js +3 -0
  41. package/dist/core/scheduler/registry.d.ts +4 -0
  42. package/dist/core/scheduler/registry.d.ts.map +1 -1
  43. package/dist/core/scheduler/types.d.ts +20 -3
  44. package/dist/core/scheduler/types.d.ts.map +1 -1
  45. package/dist/core/scheduler/windows.d.ts.map +1 -1
  46. package/dist/core/scheduler/windows.js +23 -2
  47. package/dist/core/session.d.ts +34 -0
  48. package/dist/core/session.d.ts.map +1 -0
  49. package/dist/core/session.js +105 -0
  50. package/dist/core/structured-log.d.ts +84 -0
  51. package/dist/core/structured-log.d.ts.map +1 -0
  52. package/dist/core/structured-log.js +137 -0
  53. package/dist/core/wrappers/bash.d.ts +24 -0
  54. package/dist/core/wrappers/bash.d.ts.map +1 -1
  55. package/dist/core/wrappers/bash.js +70 -3
  56. package/dist/db/history-repo.d.ts +8 -0
  57. package/dist/db/history-repo.d.ts.map +1 -1
  58. package/dist/db/history-repo.js +76 -6
  59. package/dist/db/metrics-repo.d.ts +3 -0
  60. package/dist/db/metrics-repo.d.ts.map +1 -1
  61. package/dist/db/metrics-repo.js +16 -8
  62. package/dist/db/migrate.d.ts.map +1 -1
  63. package/dist/db/migrate.js +8 -1
  64. package/dist/db/schema.d.ts +1 -1
  65. package/dist/db/schema.d.ts.map +1 -1
  66. package/dist/db/schema.js +19 -0
  67. package/dist/gui-experimental.cjs +1 -0
  68. package/dist/history.d.ts +7 -0
  69. package/dist/history.d.ts.map +1 -1
  70. package/dist/history.js +13 -0
  71. package/dist/index.d.ts +137 -1
  72. package/dist/index.d.ts.map +1 -1
  73. package/dist/index.js +1323 -78
  74. package/dist/integrations.d.ts +64 -0
  75. package/dist/integrations.d.ts.map +1 -0
  76. package/dist/integrations.js +205 -0
  77. package/dist/notifications.d.ts +112 -6
  78. package/dist/notifications.d.ts.map +1 -1
  79. package/dist/notifications.js +396 -34
  80. package/dist/profiles.d.ts +60 -0
  81. package/dist/profiles.d.ts.map +1 -0
  82. package/dist/profiles.js +209 -0
  83. package/dist/rpc.d.ts +592 -4
  84. package/dist/rpc.d.ts.map +1 -1
  85. package/dist/rpc.js +233 -6
  86. package/dist/server.d.ts +2 -0
  87. package/dist/server.d.ts.map +1 -1
  88. package/dist/server.js +473 -58
  89. package/dist/settings.d.ts +95 -0
  90. package/dist/settings.d.ts.map +1 -1
  91. package/dist/settings.js +186 -8
  92. package/dist/shared/jobs-view.d.ts +43 -5
  93. package/dist/shared/jobs-view.d.ts.map +1 -1
  94. package/dist/shared/jobs-view.js +125 -7
  95. package/dist/task-transfer.d.ts +32 -3
  96. package/dist/task-transfer.d.ts.map +1 -1
  97. package/dist/task-transfer.js +101 -3
  98. package/dist/types.d.ts.map +1 -1
  99. package/dist/types.js +3 -11
  100. package/dist/workspaces.d.ts +43 -0
  101. package/dist/workspaces.d.ts.map +1 -1
  102. package/dist/workspaces.js +174 -8
  103. package/docs/ARCHITECTURE.md +32 -12
  104. package/docs/FEATURES.md +186 -10
  105. package/gui-experimental.cjs +4 -2
  106. package/package.json +15 -2
  107. package/scripts/demo-dashboard.mjs +12 -2
  108. package/src/core/analytics.ts +36 -0
  109. package/src/core/dry-run.ts +65 -4
  110. package/src/core/matrix.ts +10 -0
  111. package/src/core/one-shot.ts +173 -0
  112. package/src/core/otel.ts +128 -0
  113. package/src/core/prometheus.ts +215 -0
  114. package/src/core/ps-wrapper.ts +144 -4
  115. package/src/core/record-history.ts +13 -0
  116. package/src/core/schedule-gate.ts +213 -0
  117. package/src/core/schedule-v2.ts +533 -0
  118. package/src/core/scheduler/linux.ts +90 -3
  119. package/src/core/scheduler/mac.ts +35 -4
  120. package/src/core/scheduler/posix.ts +3 -0
  121. package/src/core/scheduler/registry.ts +4 -0
  122. package/src/core/scheduler/types.ts +20 -3
  123. package/src/core/scheduler/windows.ts +24 -2
  124. package/src/core/session.ts +115 -0
  125. package/src/core/structured-log.ts +205 -0
  126. package/src/core/wrappers/bash.ts +98 -2
  127. package/src/db/history-repo.ts +90 -7
  128. package/src/db/metrics-repo.ts +19 -7
  129. package/src/db/migrate.ts +7 -1
  130. package/src/db/schema.ts +25 -0
  131. package/src/gui.tsx +3832 -2868
  132. package/src/history.ts +17 -0
  133. package/src/index.ts +1670 -117
  134. package/src/integrations.ts +253 -0
  135. package/src/notifications.ts +516 -40
  136. package/src/profiles.ts +236 -0
  137. package/src/rpc.ts +244 -6
  138. package/src/server.ts +506 -58
  139. package/src/settings.ts +336 -9
  140. package/src/shared/jobs-view.ts +158 -8
  141. package/src/task-transfer.ts +151 -5
  142. package/src/tui.tsx +290 -14
  143. package/src/types.ts +3 -13
  144. package/src/workspaces.ts +214 -8
@@ -86,21 +86,28 @@ is read from the database or from files under the plugin directory.
86
86
 
87
87
  1. Agent tool / GUI / import calls `schedulerCreateTask(...)`.
88
88
  2. Definitions are validated (cron, workspace path, matrix rules), a prompt file and a
89
- wrapper script are written under the plugin directory.
89
+ wrapper script are written under the plugin directory; if the task's workspace has
90
+ env variables, `<PLUGIN_DIR>/env/<sanitized>.env` is written (mode `0600` on POSIX).
90
91
  3. An OS entry is created through the platform backend.
91
92
  4. The definition is stored in `tasks.definition_json`.
92
93
 
93
94
  **Run a task**
94
95
 
95
96
  1. The OS scheduler starts the wrapper.
96
- 2. The wrapper acquires the lock (`locks/<task>.lock`), writes the log
97
- (`logs/<task>.log`), runs the pre-flight hook and starts `opencode run` with the
98
- prompt file. Output is streamed to the log.
99
- 3. When the process ends, the wrapper enforces the timeout result, runs the Quality
97
+ 2. When the task carries a schedule gate (poll-mode cron, foreign timezone or a
98
+ launch window), the wrapper first runs `node dist/core/schedule-gate.js`: it
99
+ re-checks the extended cron in the task's zone, and if now is outside the
100
+ launch window it waits until the window opens (postpone, deduplicated by a
101
+ defer-file) or exits with code 3 so the wrapper skips silently.
102
+ 3. The wrapper acquires the lock (`locks/<task>.lock`), writes the log
103
+ (`logs/<task>.log`), loads workspace env from `<PLUGIN_DIR>/env/<sanitized>.env`
104
+ (Windows `-EnvFile`, POSIX `set -a; . "$ENV_FILE"; set +a`) before starting
105
+ `opencode run` with the prompt file. Output is streamed to the log.
106
+ 4. When the process ends, the wrapper enforces the timeout result, runs the Quality
100
107
  Gate and the post-flight hook.
101
- 4. The wrapper calls `node dist/core/record-history.js --finish ...` with status,
108
+ 5. The wrapper calls `node dist/core/record-history.js --finish ...` with status,
102
109
  duration, tokens, cost, model and hook results.
103
- 5. The recorder writes `history` and updates `metrics`, then evaluates retries, task
110
+ 6. The recorder writes `history` and updates `metrics`, then evaluates retries, task
104
111
  chains, DAG dependents and matrix continuation.
105
112
 
106
113
  **Read state**
@@ -119,10 +126,11 @@ from their clones instead of their own last run.
119
126
  | `src/server.ts` | Local web dashboard HTTP server and HTML rendering |
120
127
  | `src/skill.ts` | Loads and registers the bundled agent skill |
121
128
  | `src/task-transfer.ts` | Export/import, validation, `MatrixConfig` types |
122
- | `src/workspaces.ts` | Workspace registry and path validation |
129
+ | `src/profiles.ts` | Profile directory resolution: per-profile plugin dir (base for `default`, `<base>/profiles/<name>` for named profiles); profile name, marker, port, create/delete/switch |
130
+ | `src/workspaces.ts` | Workspace registry and path validation; env pairs and `.env` file resolution with secret masking |
123
131
  | `src/templates.ts` | Reusable task templates |
124
132
  | `src/settings.ts` | Plugin settings: notifications and history retention |
125
- | `src/notifications.ts` | Webhook notifications |
133
+ | `src/notifications.ts` | Webhook delivery with retries/backoff, templates, task filters, matrix and stuck-clone notifications, daily/weekly digest |
126
134
  | `src/history.ts` | History model and status types |
127
135
  | `src/version.ts` | Runtime plugin version (reads package.json) |
128
136
  | `src/core/retention.ts` | Daily history prune and incremental vacuum |
@@ -136,6 +144,8 @@ from their clones instead of their own last run.
136
144
  | `src/core/lock.ts` | Single-instance lock manager |
137
145
  | `src/core/file-watcher.ts` | chokidar-based file triggers |
138
146
  | `src/core/cron-to-schtasks.ts` | Cron → Task Scheduler translation |
147
+ | `src/core/schedule-v2.ts` | Extended cron parser/matcher, timezone math, launch windows, poll-mode decisions |
148
+ | `src/core/schedule-gate.ts` | Wrapper-side gate: cron re-check (poll mode), window postpone, defer-file |
139
149
  | `src/db/` | SQLite access: schema, migrations, repositories, recovery |
140
150
  | `src/shared/jobs-view.ts` | Task view shared by the GUI and dashboard |
141
151
 
@@ -166,6 +176,7 @@ enforced:
166
176
  | Working directory | Task `workingDirectory`, or the workspace path, or the plugin directory |
167
177
  | Prompt | Written to a prompt file, passed to `opencode run` |
168
178
  | Timeout | `timeoutSeconds`; on expiry the child process tree is stopped and the run is marked `timeout` |
179
+ | Workspace env | Variables from the workspace's `.env` file and explicit pairs are injected before `opencode run` (wrapper `env:` / `export`); secret-looking keys are masked in logs |
169
180
  | No overlap | Lock file per task; a second start exits immediately and records `skipped` |
170
181
  | Pre-flight | `beforeScript`; non-zero exit marks `preFlight` as failed |
171
182
  | Quality Gate | `qualityGate` after a successful run; non-zero exit turns the run into an error |
@@ -238,10 +249,13 @@ remote and color. Workspaces provide:
238
249
  - the working directory for a task (`workspaceId` instead of `workingDirectory`);
239
250
  - matrix targets (`matrix.workspaceIds`);
240
251
  - per-workspace overrides (`matrix.overrides`);
241
- - dashboard grouping.
252
+ - dashboard grouping;
253
+ - env variables: explicit `KEY=VALUE` pairs plus an optional `.env` file (loaded first,
254
+ explicit pairs override), injected into task runs via the wrapper; secret-looking
255
+ keys are masked in logs.
242
256
 
243
257
  Paths are validated on creation, update and import: a workspace must point to an
244
- existing directory.
258
+ existing directory. Env keys must match `^[A-Za-z_][A-Za-z0-9_]*$`; max 100 pairs.
245
259
 
246
260
  ## Triggers
247
261
 
@@ -270,11 +284,17 @@ logs/ per-task run logs
270
284
  locks/ lock files
271
285
  wrappers/ generated .cmd / .sh wrappers
272
286
  prompts/ prompt files
287
+ env/ per-workspace env files (<task>.env), mode 0600 on POSIX
273
288
  ```
274
289
 
290
+ Named profiles (Sprint 21) each own a copy of this tree under
291
+ `<base>/profiles/<name>` (`default` uses the base directory). Profile directory,
292
+ database, settings, logs, wrappers and locks all resolve per-profile.
293
+
275
294
  Override the database location with `OPENCODE_SCHEDULER_DB` (used by tests). Override
276
295
  the whole plugin directory (database, logs, locks, wrappers, prompts) with
277
- `OPENCODE_SCHEDULER_HOME` on any platform.
296
+ `OPENCODE_SCHEDULER_HOME` on any platform. Profile selection uses
297
+ `OPENCODE_SCHEDULER_PROFILE` > `active-profile` marker > `default`.
278
298
 
279
299
  Schema evolution is additive: `applySchema` runs `CREATE TABLE IF NOT EXISTS` on every
280
300
  connection and adds missing columns after `PRAGMA table_info`, so upgrading the plugin
package/docs/FEATURES.md CHANGED
@@ -7,6 +7,8 @@ matter in practice.
7
7
  - [Execution policy](#execution-policy)
8
8
  - [Orchestration](#orchestration)
9
9
  - [Multi-repository workspaces](#multi-repository-workspaces)
10
+ - [Profiles (multi-project)](#profiles-multi-project)
11
+ - [Workspace environment variables](#workspace-environment-variables)
10
12
  - [Observability](#observability)
11
13
  - [Management](#management)
12
14
  - [Agent interface](#agent-interface)
@@ -17,7 +19,10 @@ matter in practice.
17
19
 
18
20
  ### Cron schedules
19
21
 
20
- Five-field cron: `minute hour day-of-month month day-of-week`.
22
+ Five-field cron: `minute hour day-of-month month day-of-week`. Supports lists,
23
+ ranges and steps in every field (`0 8-10,18 * * 1-5/2`), month and weekday names
24
+ (`0 9 * * MON-FRI`), `@every` sugar (`@every 15m`, `@every 2h`, `@every 1d`),
25
+ `L` as the last day of the month and the `d#n` n-th weekday form (`0 9 * * FRI#3`).
21
26
 
22
27
  | Pattern | Example | Meaning |
23
28
  | --- | --- | --- |
@@ -25,10 +30,81 @@ Five-field cron: `minute hour day-of-month month day-of-week`.
25
30
  | Fixed time | `0 9 * * *` | Daily at 09:00 |
26
31
  | Weekdays | `30 8 * * 1-5` | 08:30 Monday to Friday |
27
32
  | Monthly | `0 3 1 * *` | 03:00 on the 1st |
33
+ | Last day | `0 3 L * *` | 03:00 on the last day of the month |
34
+ | N-th weekday | `0 9 * * FRI#3` | 09:00 on the third Friday |
35
+ | Sugar | `@every 15m` | Every 15 minutes |
28
36
 
29
- The Windows backend translates cron to native Task Scheduler triggers. Expressions
30
- that `schtasks` cannot express are rejected at creation time with an explicit error
31
- instead of being silently approximated.
37
+ The Windows backend translates simple cron expressions to native Task Scheduler
38
+ triggers. Expressions `schtasks` cannot express (`L`, `#`, complex lists) or tasks
39
+ with a timezone other than the system one are registered in poll mode: the OS task
40
+ wakes the wrapper every minute and `schedule-gate` decides whether the agent runs.
41
+
42
+ ### One-shot runs
43
+
44
+ `triggerType: "once"` runs a task exactly once at a specific moment. Use either
45
+ `runAt` (ISO-8601, or a local date string such as `2026-11-13 22:40`) or
46
+ `delaySeconds` (delay from now):
47
+
48
+ ```json
49
+ {
50
+ "name": "deploy-once",
51
+ "triggerType": "once",
52
+ "runAt": "2026-11-13T22:40:00+03:00",
53
+ "prompt": "Deploy the current main branch."
54
+ }
55
+ ```
56
+
57
+ ```json
58
+ { "name": "remind-later", "triggerType": "once", "delaySeconds": 3600, "prompt": "..." }
59
+ ```
60
+
61
+ `runAt` wins when both are present. `schedule` is ignored. One-shot tasks are
62
+ registered natively (`schtasks /sc ONCE`, Linux `at`, macOS launchd cleanup
63
+ agent), are not repeated after a plugin restart, and cannot be combined with a
64
+
65
+ > **Windows locale note.** `schtasks /sd` only accepts dates in the format of the
66
+ > current Windows locale. The plugin emits `DD.MM.YYYY`, which matches Russian
67
+ > (and most European) locales. On a system with an English/US locale (`MM/DD/YYYY`)
68
+ > `schtasks` rejects the date, so one-shot tasks are not available there.
69
+ matrix.
70
+
71
+ ### Session continuity
72
+
73
+ Each scheduled run can either start a fresh OpenCode session (`new`, default),
74
+ reuse a persistent session stored on the task, or continue the latest session
75
+ (`last`, mapped to `opencode --continue`). Set `session` on the task; for
76
+ `reuse` a `sessionId` is auto-generated and stored with the task definition —
77
+ it is never accepted from user input or exported as plain text.
78
+
79
+ ```json
80
+ {
81
+ "name": "nightly-analyst",
82
+ "schedule": "0 3 * * *",
83
+ "session": "reuse",
84
+ "sessionMaxRuns": 10,
85
+ "prompt": "Refresh the analysis."
86
+ }
87
+ ```
88
+
89
+ - `session`: `new` (default), `reuse` (pass `--session <id>`), `last` (pass `--continue`).
90
+ - `sessionMaxRuns` (only for `reuse`): how many runs the reused session
91
+ survives before it is deleted (`opencode session delete`) and a fresh session
92
+ is started. Unset/0 means no limit.
93
+ - `sessionId` is per machine/profile. The internal run counter
94
+ (`sessionRunCount`) is never exported.
95
+ - Old export/import files without session fields import as `new`.
96
+
97
+ ### Timezones and launch windows
98
+
99
+ - `timezone` — IANA zone per task (e.g. `Europe/Moscow`). `nextRun`/`prevRun`,
100
+ dry-run next-run estimates and the gate evaluate cron in this zone; DST
101
+ transitions are handled (nonexistent spring-forward times are skipped).
102
+ - `notBefore` / `notAfter` — daily launch window in `HH:MM` (may cross midnight,
103
+ e.g. `22:00`–`06:00`). A run that fires outside the window is **postponed**
104
+ until the window opens (once, via a defer-file), not skipped.
105
+ - `pausedUntil` — pause a task until an ISO moment. `pause_task` accepts
106
+ `until`; the plugin re-enables the task automatically at startup and on a
107
+ 5-minute timer, and `resume_task` resumes early.
32
108
 
33
109
  ### File triggers
34
110
 
@@ -186,6 +262,42 @@ Use `workspaceId` instead of `workingDirectory` to run a task in a workspace. Pa
186
262
  validated on add/update/import, and the dashboard groups tasks and runs by workspace.
187
263
  Workspaces are the unit that matrix builds fan out to.
188
264
 
265
+ ## Profiles (multi-project, Спринт 21)
266
+
267
+ Profiles let you run several independent scheduler installations inside one plugin,
268
+ each with its own SQLite database, settings, logs, wrappers and dashboard port.
269
+ This is useful for separating projects, clients or environments (e.g. `default` and
270
+ `work`) without them seeing each other's data.
271
+
272
+ - Profile `default` uses the plugin's base directory (no migration, behaves exactly
273
+ as before Sprint 21). Named profiles live in `<base>/profiles/<name>`.
274
+ - Profile selection order: `OPENCODE_SCHEDULER_PROFILE` env var → file `active-profile`
275
+ in the base directory → `default`. Switching profiles writes the marker and requires
276
+ an OpenCode restart because plugin directories are resolved at module load time.
277
+ - Dashboard port per profile: `OPENCODE_SCHEDULER_PORT` env var → port from
278
+ `profile.json` → server default (3782, then 4782/5782 fallback).
279
+ - RPC: `get_profiles` lists profiles with dirs, ports and the active flag;
280
+ `set_profile` switches the active profile (restart hint); `create_profile` /
281
+ `delete_profile` manage named profiles (`default` cannot be deleted).
282
+
283
+ ### Workspace environment variables (Спринт 21)
284
+
285
+ Each workspace can carry env variables that are injected into every task run in that
286
+ workspace:
287
+
288
+ - `env` — explicit `KEY=VALUE` pairs stored in SQLite as JSON;
289
+ - `envFile` — optional path to a `.env` file whose variables are loaded first, then
290
+ explicit pairs override them;
291
+ - File format: `KEY=value` lines, `#` comments, blank lines, leading `export `,
292
+ values in matching quotes are unquoted;
293
+ - Key validation: `^[A-Za-z_][A-Za-z0-9_]*$`, max 100 pairs per workspace;
294
+ - Delivery: at task create/update the plugin writes `<PLUGIN_DIR>/env/<sanitized>.env`
295
+ with real values (mode `0600` on POSIX) and passes it to the wrapper
296
+ (Windows: `-EnvFile "<path>"`; POSIX: `set -a; . "$ENV_FILE"; set +a` before the
297
+ `opencode run` invocation);
298
+ - Secret masking: keys matching `/(TOKEN|SECRET|PASS|PASSWORD|KEY|CREDENTIAL|AUTH)/i`
299
+ are shown as `***` in logs and masked API responses — values never leak into logs.
300
+
189
301
  ## Observability
190
302
 
191
303
  ### History
@@ -209,7 +321,47 @@ per-day buckets (UTC), success rate, token-based cost estimate, top tasks by cos
209
321
  matrix and model breakdowns — is available through `get_analytics` /
210
322
  `GET /api/analytics` and the dashboard's «📊 Аналитика за период» block. History is
211
323
  pruned automatically (age and size limits, see Settings) and can be exported as
212
- CSV/JSON (`GET /api/history/export`).
324
+ CSV/JSON (`GET /api/history/export`), or as OTLP/JSON for OpenTelemetry
325
+ (`GET /api/history/export?format=otlp`).
326
+
327
+ ### Prometheus
328
+
329
+ `GET /metrics` exposes the Prometheus text format (0.0.4): `opencode_scheduler_info`,
330
+ `up`, `queue_depth`, `history_records`, `runs_total{task,status}`,
331
+ `errors_total{task}`, `tokens_total{task}`, `cost_usd_total{task}` and the
332
+ `run_duration_seconds` histogram (1 s … 3600 s + `+Inf`). `runs_total` has
333
+ separate `success`, `error` and `partial` statuses; `errors_total` counts only
334
+ errors and timeouts, so `partial` never inflates it. Values are read from
335
+ SQLite at scrape time, so no extra agent or exporter process is required.
336
+
337
+ ### Structured logs
338
+
339
+ Every run start/finish and every webhook decision is appended to
340
+ `<PLUGIN_DIR>/logs/runs.jsonl` (one JSON object per line, 10 MiB rotation to
341
+ `runs.jsonl.1`). `GET /api/logs` returns newest-first records and supports `task`,
342
+ `status`, `event`, `since`, `until`, `limit` and `format=jsonl`. The database
343
+ `history` table remains the source of truth for aggregates; JSONL is for log
344
+ shipping and debugging and never blocks a run if writing fails.
345
+
346
+ ### Incoming webhooks
347
+
348
+ `POST /api/hooks/:task?token=…` starts a task from GitHub Actions, GitLab CI or any
349
+ external system. The request must carry an HMAC-SHA256 of the raw body in
350
+ `X-Scheduler-Signature: sha256=<hex>` (GitHub's `X-Hub-Signature-256` and a bare
351
+ hex digest are also accepted). The token may instead come from `X-Scheduler-Token`
352
+ or `X-Gitlab-Token`. An optional `X-Scheduler-Timestamp` is checked against
353
+ `timestampToleranceSeconds`. Hooks are disabled by default; enabling them with empty
354
+ credentials generates a token and secret automatically. Errors: 401 (bad
355
+ token/signature/timestamp), 403 (channel disabled or credentials missing), 404
356
+ (unknown task), 413 (body over `maxBodyBytes`). The dashboard still binds to
357
+ localhost only, so external CI needs a tunnel or self-hosted runner.
358
+
359
+ ### OpenTelemetry
360
+
361
+ History can be exported as OTLP/JSON: one span per run, deterministic 32-hex
362
+ `traceId` and 16-hex `spanId`, nanosecond timestamps, task/status/duration/tokens/
363
+ cost/model/error attributes and OK/ERROR status. The output can be posted to an
364
+ OpenTelemetry Collector or inspected directly.
213
365
 
214
366
  ### Logs
215
367
 
@@ -248,6 +400,25 @@ matrix combinations are rejected explicitly.
248
400
  Webhook notifications on run completion, configurable in settings and testable with
249
401
  `test_notification`.
250
402
 
403
+ - **Delivery:** per-task completion (success/error/timeout) through a Discord/Slack
404
+ compatible webhook (`{ content, text }`). `webhook.timeoutMs` (default 10 000),
405
+ `webhook.retryCount` (default 2) and `webhook.retryDelayMs` (default 1000) control
406
+ the request; network errors, timeouts, HTTP 5xx and 429 are retried with exponential
407
+ backoff (capped at 30 s), other 4xx are not.
408
+ - **Templates:** `templates.success` and `templates.error` accept placeholders
409
+ `{task}`, `{status}`, `{duration}`, `{error}`, `{emoji}`.
410
+ - **Filters:** `filters.include` / `filters.exclude` are task-name patterns with `*`
411
+ wildcards; an empty include list means all tasks, exclude wins.
412
+ - **Matrix notifications:** on family completion — success, `partial` (`onPartial`)
413
+ and all clones failed (`onAllFailed`). A stuck detector reports clones running
414
+ longer than `matrix.stuckAfterMinutes` (default 60, `0` disables) once per run.
415
+ - **Digest:** `digest.enabled` sends a daily (`frequency: "daily"`, at `digest.time`)
416
+ or weekly (Mondays, catch-up afterwards) summary: runs, success rate, cost, tokens
417
+ and top errors. Also available as the `send_digest` RPC and the GUI's
418
+ «📊 Отправить дайджест сейчас» button (manual sends do not move the schedule).
419
+ - **ntfy.sh is intentionally not implemented** (excluded by the assignment); the
420
+ network channel is the webhook, plus GUI toasts for manual runs.
421
+
251
422
  ### Crash recovery
252
423
 
253
424
  Runs left in `running` after a crash are marked `error` on the next plugin start, so
@@ -265,9 +436,12 @@ the `cleanup_history` RPC and the GUI's «Очистить сейчас» button
265
436
 
266
437
  ## Agent interface
267
438
 
268
- Twelve tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
439
+ Twenty-two tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
269
440
  `run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
270
- `manage_workspaces`, `matrix_control`.
441
+ `manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
442
+ `get_analytics`, `manage_settings`, `manage_templates`, `manage_profiles`,
443
+ `transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
444
+ `emit_event`.
271
445
 
272
446
  A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
273
447
  least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
@@ -287,9 +461,11 @@ plugin, no installation step required.
287
461
 
288
462
  ## Limits and non-goals
289
463
 
290
- - **No one-shot scheduling yet.** Only cron, file and MCP-event triggers exist; use
291
- `run_task_now` for immediate runs. A one-shot trigger is on the roadmap.
292
- - **No session continuity.** Every run starts a fresh `opencode run` session.
464
+ - **No one-shot scheduling without `triggerType: "once"`.** One-shot runs exist
465
+ via `runAt`/`delaySeconds`; use `run_task_now` for immediate runs.
466
+ - **No session continuity beyond the built-in `session` modes.** `new`, `reuse`
467
+ and `last` cover the common cases; per-message session forking/branching is
468
+ not supported.
293
469
  - **No sandbox.** Hooks, Quality Gates and prompts run with your user privileges.
294
470
  - **No authentication on the dashboard.** Localhost only by design.
295
471
  - **Secrets are not encrypted.** Use environment variables or an external secret