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.
- package/CHANGELOG.md +60 -1
- package/README.md +18 -8
- package/README.ru.md +13 -3
- package/ROADMAP-STRATEGY.md +2 -2
- package/ROADMAP.md +51 -18
- package/dist/core/analytics.d.ts +10 -0
- package/dist/core/analytics.d.ts.map +1 -1
- package/dist/core/analytics.js +21 -0
- package/dist/core/dry-run.d.ts +18 -1
- package/dist/core/dry-run.d.ts.map +1 -1
- package/dist/core/dry-run.js +49 -3
- package/dist/core/matrix.d.ts.map +1 -1
- package/dist/core/matrix.js +10 -0
- package/dist/core/one-shot.d.ts +62 -0
- package/dist/core/one-shot.d.ts.map +1 -0
- package/dist/core/one-shot.js +126 -0
- package/dist/core/otel.d.ts +4 -0
- package/dist/core/otel.d.ts.map +1 -0
- package/dist/core/otel.js +98 -0
- package/dist/core/prometheus.d.ts +23 -0
- package/dist/core/prometheus.d.ts.map +1 -0
- package/dist/core/prometheus.js +146 -0
- package/dist/core/ps-wrapper.d.ts +36 -2
- package/dist/core/ps-wrapper.d.ts.map +1 -1
- package/dist/core/ps-wrapper.js +124 -4
- package/dist/core/record-history.d.ts.map +1 -1
- package/dist/core/record-history.js +9 -0
- package/dist/core/schedule-gate.d.ts +2 -0
- package/dist/core/schedule-gate.d.ts.map +1 -0
- package/dist/core/schedule-gate.js +182 -0
- package/dist/core/schedule-v2.d.ts +88 -0
- package/dist/core/schedule-v2.d.ts.map +1 -0
- package/dist/core/schedule-v2.js +496 -0
- package/dist/core/scheduler/linux.d.ts +12 -3
- package/dist/core/scheduler/linux.d.ts.map +1 -1
- package/dist/core/scheduler/linux.js +80 -3
- package/dist/core/scheduler/mac.d.ts.map +1 -1
- package/dist/core/scheduler/mac.js +17 -3
- package/dist/core/scheduler/posix.d.ts.map +1 -1
- package/dist/core/scheduler/posix.js +3 -0
- package/dist/core/scheduler/registry.d.ts +4 -0
- package/dist/core/scheduler/registry.d.ts.map +1 -1
- package/dist/core/scheduler/types.d.ts +20 -3
- package/dist/core/scheduler/types.d.ts.map +1 -1
- package/dist/core/scheduler/windows.d.ts.map +1 -1
- package/dist/core/scheduler/windows.js +23 -2
- package/dist/core/session.d.ts +34 -0
- package/dist/core/session.d.ts.map +1 -0
- package/dist/core/session.js +105 -0
- package/dist/core/structured-log.d.ts +84 -0
- package/dist/core/structured-log.d.ts.map +1 -0
- package/dist/core/structured-log.js +137 -0
- package/dist/core/wrappers/bash.d.ts +24 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -1
- package/dist/core/wrappers/bash.js +70 -3
- package/dist/db/history-repo.d.ts +8 -0
- package/dist/db/history-repo.d.ts.map +1 -1
- package/dist/db/history-repo.js +76 -6
- package/dist/db/metrics-repo.d.ts +3 -0
- package/dist/db/metrics-repo.d.ts.map +1 -1
- package/dist/db/metrics-repo.js +16 -8
- package/dist/db/migrate.d.ts.map +1 -1
- package/dist/db/migrate.js +8 -1
- package/dist/db/schema.d.ts +1 -1
- package/dist/db/schema.d.ts.map +1 -1
- package/dist/db/schema.js +19 -0
- package/dist/gui-experimental.cjs +1 -0
- package/dist/history.d.ts +7 -0
- package/dist/history.d.ts.map +1 -1
- package/dist/history.js +13 -0
- package/dist/index.d.ts +137 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1323 -78
- package/dist/integrations.d.ts +64 -0
- package/dist/integrations.d.ts.map +1 -0
- package/dist/integrations.js +205 -0
- package/dist/notifications.d.ts +112 -6
- package/dist/notifications.d.ts.map +1 -1
- package/dist/notifications.js +396 -34
- package/dist/profiles.d.ts +60 -0
- package/dist/profiles.d.ts.map +1 -0
- package/dist/profiles.js +209 -0
- package/dist/rpc.d.ts +592 -4
- package/dist/rpc.d.ts.map +1 -1
- package/dist/rpc.js +233 -6
- package/dist/server.d.ts +2 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +473 -58
- package/dist/settings.d.ts +95 -0
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +186 -8
- package/dist/shared/jobs-view.d.ts +43 -5
- package/dist/shared/jobs-view.d.ts.map +1 -1
- package/dist/shared/jobs-view.js +125 -7
- package/dist/task-transfer.d.ts +32 -3
- package/dist/task-transfer.d.ts.map +1 -1
- package/dist/task-transfer.js +101 -3
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +3 -11
- package/dist/workspaces.d.ts +43 -0
- package/dist/workspaces.d.ts.map +1 -1
- package/dist/workspaces.js +174 -8
- package/docs/ARCHITECTURE.md +32 -12
- package/docs/FEATURES.md +186 -10
- package/gui-experimental.cjs +4 -2
- package/package.json +15 -2
- package/scripts/demo-dashboard.mjs +12 -2
- package/src/core/analytics.ts +36 -0
- package/src/core/dry-run.ts +65 -4
- package/src/core/matrix.ts +10 -0
- package/src/core/one-shot.ts +173 -0
- package/src/core/otel.ts +128 -0
- package/src/core/prometheus.ts +215 -0
- package/src/core/ps-wrapper.ts +144 -4
- package/src/core/record-history.ts +13 -0
- package/src/core/schedule-gate.ts +213 -0
- package/src/core/schedule-v2.ts +533 -0
- package/src/core/scheduler/linux.ts +90 -3
- package/src/core/scheduler/mac.ts +35 -4
- package/src/core/scheduler/posix.ts +3 -0
- package/src/core/scheduler/registry.ts +4 -0
- package/src/core/scheduler/types.ts +20 -3
- package/src/core/scheduler/windows.ts +24 -2
- package/src/core/session.ts +115 -0
- package/src/core/structured-log.ts +205 -0
- package/src/core/wrappers/bash.ts +98 -2
- package/src/db/history-repo.ts +90 -7
- package/src/db/metrics-repo.ts +19 -7
- package/src/db/migrate.ts +7 -1
- package/src/db/schema.ts +25 -0
- package/src/gui.tsx +3832 -2868
- package/src/history.ts +17 -0
- package/src/index.ts +1670 -117
- package/src/integrations.ts +253 -0
- package/src/notifications.ts +516 -40
- package/src/profiles.ts +236 -0
- package/src/rpc.ts +244 -6
- package/src/server.ts +506 -58
- package/src/settings.ts +336 -9
- package/src/shared/jobs-view.ts +158 -8
- package/src/task-transfer.ts +151 -5
- package/src/tui.tsx +290 -14
- package/src/types.ts +3 -13
- package/src/workspaces.ts +214 -8
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -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.
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
-
|
|
108
|
+
5. The wrapper calls `node dist/core/record-history.js --finish ...` with status,
|
|
102
109
|
duration, tokens, cost, model and hook results.
|
|
103
|
-
|
|
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/
|
|
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
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
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
|
|
291
|
-
`run_task_now` for immediate runs.
|
|
292
|
-
- **No session continuity
|
|
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
|