opencode-windows-scheduler 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +45 -0
- package/CROSS_PLATFORM.md +113 -0
- package/LICENSE +21 -0
- package/README.md +173 -2
- package/README.ru.md +131 -0
- package/ROADMAP-STRATEGY.md +217 -0
- package/ROADMAP.md +87 -0
- package/dist/core/cron-to-schtasks.d.ts +20 -0
- package/dist/core/cron-to-schtasks.d.ts.map +1 -0
- package/dist/core/cron-to-schtasks.js +233 -0
- package/dist/core/dry-run.d.ts +44 -0
- package/dist/core/dry-run.d.ts.map +1 -0
- package/dist/core/dry-run.js +252 -0
- package/dist/core/file-watcher.d.ts +31 -0
- package/dist/core/file-watcher.d.ts.map +1 -0
- package/dist/core/file-watcher.js +128 -0
- package/dist/core/lock.d.ts +43 -0
- package/dist/core/lock.d.ts.map +1 -0
- package/dist/core/lock.js +118 -0
- package/dist/core/matrix.d.ts +167 -0
- package/dist/core/matrix.d.ts.map +1 -0
- package/dist/core/matrix.js +687 -0
- package/dist/core/ps-wrapper.d.ts +60 -0
- package/dist/core/ps-wrapper.d.ts.map +1 -0
- package/dist/core/ps-wrapper.js +538 -0
- package/dist/core/record-history.d.ts +14 -0
- package/dist/core/record-history.d.ts.map +1 -0
- package/dist/core/record-history.js +360 -0
- package/dist/core/scheduler/index.d.ts +20 -0
- package/dist/core/scheduler/index.d.ts.map +1 -0
- package/dist/core/scheduler/index.js +32 -0
- package/dist/core/scheduler/linux.d.ts +32 -0
- package/dist/core/scheduler/linux.d.ts.map +1 -0
- package/dist/core/scheduler/linux.js +115 -0
- package/dist/core/scheduler/logs.d.ts +11 -0
- package/dist/core/scheduler/logs.d.ts.map +1 -0
- package/dist/core/scheduler/logs.js +34 -0
- package/dist/core/scheduler/mac.d.ts +39 -0
- package/dist/core/scheduler/mac.d.ts.map +1 -0
- package/dist/core/scheduler/mac.js +175 -0
- package/dist/core/scheduler/posix.d.ts +40 -0
- package/dist/core/scheduler/posix.d.ts.map +1 -0
- package/dist/core/scheduler/posix.js +86 -0
- package/dist/core/scheduler/registry.d.ts +36 -0
- package/dist/core/scheduler/registry.d.ts.map +1 -0
- package/dist/core/scheduler/registry.js +56 -0
- package/dist/core/scheduler/types.d.ts +63 -0
- package/dist/core/scheduler/types.d.ts.map +1 -0
- package/dist/core/scheduler/types.js +1 -0
- package/dist/core/scheduler/windows.d.ts +47 -0
- package/dist/core/scheduler/windows.d.ts.map +1 -0
- package/dist/core/scheduler/windows.js +375 -0
- package/dist/core/wrappers/bash.d.ts +58 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -0
- package/dist/core/wrappers/bash.js +223 -0
- package/dist/db/history-repo.d.ts +69 -0
- package/dist/db/history-repo.d.ts.map +1 -0
- package/dist/db/history-repo.js +150 -0
- package/dist/db/index.d.ts +47 -0
- package/dist/db/index.d.ts.map +1 -0
- package/dist/db/index.js +120 -0
- package/dist/db/metrics-repo.d.ts +43 -0
- package/dist/db/metrics-repo.d.ts.map +1 -0
- package/dist/db/metrics-repo.js +95 -0
- package/dist/db/migrate.d.ts +24 -0
- package/dist/db/migrate.d.ts.map +1 -0
- package/dist/db/migrate.js +237 -0
- package/dist/db/recovery.d.ts +11 -0
- package/dist/db/recovery.d.ts.map +1 -0
- package/dist/db/recovery.js +38 -0
- package/dist/db/schema.d.ts +24 -0
- package/dist/db/schema.d.ts.map +1 -0
- package/dist/db/schema.js +97 -0
- package/dist/db/settings-repo.d.ts +8 -0
- package/dist/db/settings-repo.d.ts.map +1 -0
- package/dist/db/settings-repo.js +27 -0
- package/dist/db/tasks-repo.d.ts +26 -0
- package/dist/db/tasks-repo.d.ts.map +1 -0
- package/dist/db/tasks-repo.js +120 -0
- package/dist/db/templates-repo.d.ts +17 -0
- package/dist/db/templates-repo.d.ts.map +1 -0
- package/dist/db/templates-repo.js +57 -0
- package/dist/gui-experimental.cjs +1 -0
- package/dist/history.d.ts +53 -0
- package/dist/history.d.ts.map +1 -0
- package/dist/history.js +57 -0
- package/dist/index.d.ts +156 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2077 -0
- package/dist/notifications.d.ts +45 -0
- package/dist/notifications.d.ts.map +1 -0
- package/dist/notifications.js +135 -0
- package/dist/rpc.d.ts +2052 -0
- package/dist/rpc.d.ts.map +1 -0
- package/dist/rpc.js +863 -0
- package/dist/schtasks.d.ts +32 -0
- package/dist/schtasks.d.ts.map +1 -0
- package/dist/schtasks.js +45 -0
- package/dist/server.d.ts +106 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +1478 -0
- package/dist/settings.d.ts +43 -0
- package/dist/settings.d.ts.map +1 -0
- package/dist/settings.js +96 -0
- package/dist/shared/jobs-view.d.ts +21 -0
- package/dist/shared/jobs-view.d.ts.map +1 -0
- package/dist/shared/jobs-view.js +28 -0
- package/dist/skill.d.ts +15 -0
- package/dist/skill.d.ts.map +1 -0
- package/dist/skill.js +93 -0
- package/dist/task-transfer.d.ts +176 -0
- package/dist/task-transfer.d.ts.map +1 -0
- package/dist/task-transfer.js +442 -0
- package/dist/templates.d.ts +57 -0
- package/dist/templates.d.ts.map +1 -0
- package/dist/templates.js +16 -0
- package/dist/types.d.ts +78 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +88 -0
- package/dist/workspaces.d.ts +55 -0
- package/dist/workspaces.d.ts.map +1 -0
- package/dist/workspaces.js +183 -0
- package/docs/ARCHITECTURE.md +302 -0
- package/docs/FEATURES.md +288 -0
- package/docs/MIGRATION.md +266 -0
- package/docs/dashboard.png +0 -0
- package/gui-experimental.cjs +2 -0
- package/index.js +1 -0
- package/package.json +92 -4
- package/scripts/demo-dashboard.mjs +199 -0
- package/skills/scheduled-job-best-practices/SKILL.md +155 -0
- package/skills/scheduled-job-best-practices/references/recipes.md +123 -0
- package/src/core/cron-to-schtasks.ts +269 -0
- package/src/core/dry-run.ts +315 -0
- package/src/core/file-watcher.ts +171 -0
- package/src/core/lock.ts +134 -0
- package/src/core/matrix.ts +907 -0
- package/src/core/ps-wrapper.ts +572 -0
- package/src/core/record-history.ts +493 -0
- package/src/core/scheduler/index.ts +44 -0
- package/src/core/scheduler/linux.ts +125 -0
- package/src/core/scheduler/logs.ts +37 -0
- package/src/core/scheduler/mac.ts +222 -0
- package/src/core/scheduler/posix.ts +111 -0
- package/src/core/scheduler/registry.ts +93 -0
- package/src/core/scheduler/types.ts +67 -0
- package/src/core/scheduler/windows.ts +469 -0
- package/src/core/wrappers/bash.ts +282 -0
- package/src/db/history-repo.ts +303 -0
- package/src/db/index.ts +166 -0
- package/src/db/metrics-repo.ts +158 -0
- package/src/db/migrate.ts +322 -0
- package/src/db/recovery.ts +46 -0
- package/src/db/schema.ts +109 -0
- package/src/db/settings-repo.ts +31 -0
- package/src/db/tasks-repo.ts +162 -0
- package/src/db/templates-repo.ts +77 -0
- package/src/gui.tsx +2725 -0
- package/src/history.ts +107 -0
- package/src/index.ts +2672 -0
- package/src/notifications.ts +174 -0
- package/src/rpc.ts +933 -0
- package/src/schtasks.ts +75 -0
- package/src/server.ts +1663 -0
- package/src/settings.ts +157 -0
- package/src/shared/jobs-view.ts +38 -0
- package/src/skill.ts +113 -0
- package/src/task-transfer.ts +648 -0
- package/src/templates.ts +67 -0
- package/src/tui.tsx +46 -0
- package/src/types.ts +145 -0
- package/src/workspaces.ts +236 -0
package/docs/FEATURES.md
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
# Features
|
|
2
|
+
|
|
3
|
+
A complete catalog of what the scheduler can do, with examples and the caveats that
|
|
4
|
+
matter in practice.
|
|
5
|
+
|
|
6
|
+
- [Scheduling](#scheduling)
|
|
7
|
+
- [Execution policy](#execution-policy)
|
|
8
|
+
- [Orchestration](#orchestration)
|
|
9
|
+
- [Multi-repository workspaces](#multi-repository-workspaces)
|
|
10
|
+
- [Observability](#observability)
|
|
11
|
+
- [Management](#management)
|
|
12
|
+
- [Agent interface](#agent-interface)
|
|
13
|
+
- [Platform support](#platform-support)
|
|
14
|
+
- [Limits and non-goals](#limits-and-non-goals)
|
|
15
|
+
|
|
16
|
+
## Scheduling
|
|
17
|
+
|
|
18
|
+
### Cron schedules
|
|
19
|
+
|
|
20
|
+
Five-field cron: `minute hour day-of-month month day-of-week`.
|
|
21
|
+
|
|
22
|
+
| Pattern | Example | Meaning |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| Every N minutes | `*/15 * * * *` | Every 15 minutes |
|
|
25
|
+
| Fixed time | `0 9 * * *` | Daily at 09:00 |
|
|
26
|
+
| Weekdays | `30 8 * * 1-5` | 08:30 Monday to Friday |
|
|
27
|
+
| Monthly | `0 3 1 * *` | 03:00 on the 1st |
|
|
28
|
+
|
|
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.
|
|
32
|
+
|
|
33
|
+
### File triggers
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"name": "regen-api-client",
|
|
38
|
+
"triggerType": "file",
|
|
39
|
+
"watchPath": "C:\\projects\\api\\openapi.yaml",
|
|
40
|
+
"prompt": "Regenerate the API client from openapi.yaml and run contract tests."
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The file is watched with chokidar in the plugin host, changes are debounced. File
|
|
45
|
+
triggers ignore `schedule`.
|
|
46
|
+
|
|
47
|
+
### MCP event triggers
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"name": "on-pr-opened",
|
|
52
|
+
"triggerType": "mcp-event",
|
|
53
|
+
"mcpEvent": { "server": "github", "event": "pull_request.opened", "filter": "repo=acme/api" },
|
|
54
|
+
"prompt": "Review the newly opened pull request."
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Events are emitted through the `emit_event` RPC method.
|
|
59
|
+
|
|
60
|
+
### Manual runs and pause
|
|
61
|
+
|
|
62
|
+
- `run_task_now` starts a task immediately, through the same wrapper (timeout, lock,
|
|
63
|
+
hooks, Quality Gate).
|
|
64
|
+
- `pause_task` / `resume_task` disable and re-enable the OS entry. For a matrix parent
|
|
65
|
+
every clone is paused.
|
|
66
|
+
|
|
67
|
+
## Execution policy
|
|
68
|
+
|
|
69
|
+
### Timeout and no-overlap
|
|
70
|
+
|
|
71
|
+
Every run has `timeoutSeconds` (default 3600). On expiry the process tree is stopped
|
|
72
|
+
and the run is recorded as `timeout`. A lock file prevents two runs of the same task
|
|
73
|
+
from overlapping; the second start exits immediately and is recorded as `skipped`.
|
|
74
|
+
|
|
75
|
+
### Pre-flight, Quality Gate, post-flight
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"name": "nightly-deps",
|
|
80
|
+
"schedule": "0 2 * * *",
|
|
81
|
+
"beforeScript": "git pull --ff-only",
|
|
82
|
+
"prompt": "Update dependencies, fix breaking changes, keep the diff minimal.",
|
|
83
|
+
"qualityGate": "npm test",
|
|
84
|
+
"afterScript": "git push",
|
|
85
|
+
"timeoutSeconds": 2400
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
| Hook | When | Effect of non-zero exit |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| `beforeScript` | before the agent starts | run is cancelled, pre-flight marked failed |
|
|
92
|
+
| `qualityGate` | after a successful response | run is marked as a Quality Gate failure (error) |
|
|
93
|
+
| `afterScript` | after the run, even on failure | reported in history, does not rewrite a success |
|
|
94
|
+
|
|
95
|
+
### Retries
|
|
96
|
+
|
|
97
|
+
`retryCount` and `retryDelay` (seconds) retry a failed run. Retry state is persisted,
|
|
98
|
+
so a crash cannot produce an infinite retry loop. Retries happen before chains and
|
|
99
|
+
dependents.
|
|
100
|
+
|
|
101
|
+
### Model and priority
|
|
102
|
+
|
|
103
|
+
`model` selects an OpenCode model (for example `anthropic/claude-3-5-sonnet`);
|
|
104
|
+
omitting it uses the OpenCode default. `priority` is `0..10` and is passed through to
|
|
105
|
+
the scheduler entry.
|
|
106
|
+
|
|
107
|
+
### Tool restrictions
|
|
108
|
+
|
|
109
|
+
`allowedTools` and `deniedTools` declare the intended role of the job. They are
|
|
110
|
+
recorded in history for audit. They are **metadata, not a sandbox**: they do not
|
|
111
|
+
restrict `opencode` at runtime today.
|
|
112
|
+
|
|
113
|
+
## Orchestration
|
|
114
|
+
|
|
115
|
+
### Chains
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{ "name": "build", "nextTaskOnSuccess": "deploy", "nextTaskOnError": "notify-failure" }
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Exactly one follow-up task is started after a run.
|
|
122
|
+
|
|
123
|
+
### DAG dependencies
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{ "name": "smoke-tests", "dependsOn": ["deploy"], "schedule": "0 * * * *" }
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
A dependent starts only when every dependency's latest run is successful. If a
|
|
130
|
+
dependency is a matrix, **all clones** must be successful — a `partial` matrix blocks
|
|
131
|
+
dependents.
|
|
132
|
+
|
|
133
|
+
### Matrix builds (fan-out)
|
|
134
|
+
|
|
135
|
+
One definition, one clone per workspace:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"name": "deploy",
|
|
140
|
+
"schedule": "0 3 * * *",
|
|
141
|
+
"prompt": "Build, test and deploy this repository. Report what changed.",
|
|
142
|
+
"matrix": {
|
|
143
|
+
"workspaceIds": ["ws-frontend", "ws-backend", "ws-mobile"],
|
|
144
|
+
"strategy": "parallel",
|
|
145
|
+
"failureMode": "continue",
|
|
146
|
+
"concurrency": 2,
|
|
147
|
+
"overrides": {
|
|
148
|
+
"ws-mobile": { "qualityGate": "flutter test", "prompt": "Use the Flutter toolchain." }
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
| Field | Default | Meaning |
|
|
155
|
+
| --- | --- | --- |
|
|
156
|
+
| `strategy` | `parallel` | `sequential` starts the next clone only after the previous one finishes |
|
|
157
|
+
| `failureMode` | `continue` | `stop` aborts the remaining clones after the first failure |
|
|
158
|
+
| `concurrency` | unlimited | Maximum clones running at once (ignored for `sequential`) |
|
|
159
|
+
| `aggregation` | `summary` | `summary` writes one aggregate record for the parent |
|
|
160
|
+
| `createAggregator` | `false` | Also create `<parent>-matrix-complete` depending on every clone |
|
|
161
|
+
| `overrides` | none | Per-workspace prompt/model/Quality Gate/hooks |
|
|
162
|
+
|
|
163
|
+
Behavior worth knowing:
|
|
164
|
+
|
|
165
|
+
- Clones are named `<parent>-matrix-<workspace>`, inherit the parent definition and get
|
|
166
|
+
their own working directory.
|
|
167
|
+
- The parent never runs itself; its status is the aggregate: `success`, `error`,
|
|
168
|
+
`partial` (some clones failed under `continue`), or `running`.
|
|
169
|
+
- Editing the parent (workspaces, prompt, overrides, concurrency) **syncs** the clone
|
|
170
|
+
set: missing clones are created, changed ones updated, removed ones deleted. Clones
|
|
171
|
+
with a running job are never touched.
|
|
172
|
+
- Cancelling a matrix (`matrix_control` with `action: "cancel"`) marks pending clones
|
|
173
|
+
as cancelled and stops running ones. Deleting a parent deletes its whole family.
|
|
174
|
+
- `matrix_control` with `action: "cleanup"` removes orphaned clones whose parent is
|
|
175
|
+
gone; the same cleanup also runs at plugin startup.
|
|
176
|
+
|
|
177
|
+
## Multi-repository workspaces
|
|
178
|
+
|
|
179
|
+
A workspace is a named directory: id, name, path, optional git remote and color.
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{ "id": "ws-api", "name": "API", "path": "C:\\projects\\api", "color": "#3b82f6" }
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Use `workspaceId` instead of `workingDirectory` to run a task in a workspace. Paths are
|
|
186
|
+
validated on add/update/import, and the dashboard groups tasks and runs by workspace.
|
|
187
|
+
Workspaces are the unit that matrix builds fan out to.
|
|
188
|
+
|
|
189
|
+
## Observability
|
|
190
|
+
|
|
191
|
+
### History
|
|
192
|
+
|
|
193
|
+
Every run becomes a row: status, start/finish, duration, error, tokens, cost, model,
|
|
194
|
+
pre/post-flight results, next chained task, workspace and tool restrictions. Statuses:
|
|
195
|
+
|
|
196
|
+
| Status | Meaning |
|
|
197
|
+
| --- | --- |
|
|
198
|
+
| `running` | started, not finished |
|
|
199
|
+
| `success` | finished, no Quality Gate failure |
|
|
200
|
+
| `error` | agent error, hook failure or Quality Gate failure |
|
|
201
|
+
| `timeout` | killed by the timeout |
|
|
202
|
+
| `partial` | matrix aggregate with both successes and failures |
|
|
203
|
+
|
|
204
|
+
### Metrics
|
|
205
|
+
|
|
206
|
+
Per-task counters and totals: runs, successes, errors, tokens, cost. Available through
|
|
207
|
+
`get_history`, the RPC layer and the dashboard header.
|
|
208
|
+
|
|
209
|
+
### Logs
|
|
210
|
+
|
|
211
|
+
Each run appends to `logs/<task>.log` — pre/post hooks, Quality Gate output and the
|
|
212
|
+
agent's stdout/stderr. `get_task_logs` returns the tail (1–1000 lines).
|
|
213
|
+
|
|
214
|
+
### Dry run
|
|
215
|
+
|
|
216
|
+
`dry_run` simulates one task or every task: execution order, DAG prerequisites, matrix
|
|
217
|
+
fan-out and estimated time. Nothing is executed and nothing is created.
|
|
218
|
+
|
|
219
|
+
### Dashboard
|
|
220
|
+
|
|
221
|
+
A local web dashboard shows tasks, matrix tabs, per-workspace summaries, DAG markers,
|
|
222
|
+
metrics and recent runs. It binds to localhost and has no authentication — do not
|
|
223
|
+
expose it.
|
|
224
|
+
|
|
225
|
+
## Management
|
|
226
|
+
|
|
227
|
+
### Templates
|
|
228
|
+
|
|
229
|
+
Save a definition as a reusable template, then create tasks from it with one click or
|
|
230
|
+
one tool call.
|
|
231
|
+
|
|
232
|
+
### Export and import
|
|
233
|
+
|
|
234
|
+
`export_tasks` produces a versioned JSON document with definitions, including matrix
|
|
235
|
+
configuration and `matrixParentId`. `import_tasks` validates every record and reports
|
|
236
|
+
per-record errors instead of failing the whole batch. Unknown workspaces and invalid
|
|
237
|
+
matrix combinations are rejected explicitly.
|
|
238
|
+
|
|
239
|
+
### Notifications
|
|
240
|
+
|
|
241
|
+
Webhook notifications on run completion, configurable in settings and testable with
|
|
242
|
+
`test_notification`.
|
|
243
|
+
|
|
244
|
+
### Crash recovery
|
|
245
|
+
|
|
246
|
+
Runs left in `running` after a crash are marked `error` on the next plugin start, so
|
|
247
|
+
the timeline never lies. Orphaned matrix clones are cleaned up at startup as well.
|
|
248
|
+
|
|
249
|
+
### Settings
|
|
250
|
+
|
|
251
|
+
Global defaults (timeout, concurrency, notifications) live in the `settings` table and
|
|
252
|
+
are editable from the GUI/RPC layer.
|
|
253
|
+
|
|
254
|
+
## Agent interface
|
|
255
|
+
|
|
256
|
+
Twelve tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
|
|
257
|
+
`run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
|
|
258
|
+
`manage_workspaces`, `matrix_control`.
|
|
259
|
+
|
|
260
|
+
A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
|
|
261
|
+
least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
|
|
262
|
+
create → dry-run → run-now → inspect loop. It is registered automatically by the
|
|
263
|
+
plugin, no installation step required.
|
|
264
|
+
|
|
265
|
+
## Platform support
|
|
266
|
+
|
|
267
|
+
| Capability | Windows | Linux | macOS |
|
|
268
|
+
| --- | --- | --- | --- |
|
|
269
|
+
| Cron scheduling | Task Scheduler | crontab | launchd |
|
|
270
|
+
| Fallback | — | — | crontab |
|
|
271
|
+
| Timeout and lock | PowerShell wrapper | bash wrapper | bash wrapper |
|
|
272
|
+
| File triggers | chokidar | chokidar | chokidar |
|
|
273
|
+
| History, metrics, dashboard | yes | yes | yes |
|
|
274
|
+
| Agent tools and skill | yes | yes | yes |
|
|
275
|
+
|
|
276
|
+
## Limits and non-goals
|
|
277
|
+
|
|
278
|
+
- **No one-shot scheduling yet.** Only cron, file and MCP-event triggers exist; use
|
|
279
|
+
`run_task_now` for immediate runs. A one-shot trigger is on the roadmap.
|
|
280
|
+
- **No session continuity.** Every run starts a fresh `opencode run` session.
|
|
281
|
+
- **No sandbox.** Hooks, Quality Gates and prompts run with your user privileges.
|
|
282
|
+
- **No authentication on the dashboard.** Localhost only by design.
|
|
283
|
+
- **Secrets are not encrypted.** Use environment variables or an external secret
|
|
284
|
+
manager.
|
|
285
|
+
- **`allowedTools` / `deniedTools` are advisory.** They document intent and are
|
|
286
|
+
recorded in history; enforcement is not implemented.
|
|
287
|
+
- **Matrix clones are separate tasks.** They appear in the task list (grouped under the
|
|
288
|
+
parent) and consume global concurrency slots like any other run.
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
# Migration guide
|
|
2
|
+
|
|
3
|
+
How to move existing automation into `opencode-windows-scheduler` from cron, systemd
|
|
4
|
+
timers, launchd, Windows Task Scheduler, or another scheduler plugin.
|
|
5
|
+
|
|
6
|
+
- [Before you start](#before-you-start)
|
|
7
|
+
- [From cron / crontab](#from-cron--crontab)
|
|
8
|
+
- [From systemd timers](#from-systemd-timers)
|
|
9
|
+
- [From launchd](#from-launchd)
|
|
10
|
+
- [From Windows Task Scheduler](#from-windows-task-scheduler)
|
|
11
|
+
- [From another scheduler plugin](#from-another-scheduler-plugin)
|
|
12
|
+
- [Bulk import and export](#bulk-import-and-export)
|
|
13
|
+
- [Verification checklist](#verification-checklist)
|
|
14
|
+
- [Common pitfalls](#common-pitfalls)
|
|
15
|
+
- [Rollback](#rollback)
|
|
16
|
+
|
|
17
|
+
## Before you start
|
|
18
|
+
|
|
19
|
+
1. **Install and build.**
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install -g opencode-windows-scheduler
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Add the plugin to `opencode.json` and restart OpenCode. If OpenCode's built-in
|
|
26
|
+
schedules are enabled, disable them so two schedulers do not run the same work.
|
|
27
|
+
|
|
28
|
+
2. **Check Node.** `node --version` must be 20 or newer (22.5+ for the built-in SQLite
|
|
29
|
+
driver; Node 24 recommended).
|
|
30
|
+
|
|
31
|
+
3. **Inventory the old jobs.** For each job write down: name, schedule, command,
|
|
32
|
+
working directory, environment variables, timeout, and what "success" means. The
|
|
33
|
+
last one becomes your Quality Gate.
|
|
34
|
+
|
|
35
|
+
4. **Do not delete the old jobs yet.** Run both schedulers side by side for a few days,
|
|
36
|
+
then remove the old entries.
|
|
37
|
+
|
|
38
|
+
## From cron / crontab
|
|
39
|
+
|
|
40
|
+
Cron expressions are compatible (five fields). The differences are in the command.
|
|
41
|
+
|
|
42
|
+
**Before (crontab)**
|
|
43
|
+
|
|
44
|
+
```cron
|
|
45
|
+
0 2 * * * cd /srv/api && /usr/bin/git pull && /usr/bin/npm test >> /var/log/api.log 2>&1
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**After (agent tool or GUI)**
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"name": "api-nightly",
|
|
53
|
+
"schedule": "0 2 * * *",
|
|
54
|
+
"workingDirectory": "/srv/api",
|
|
55
|
+
"beforeScript": "git pull --ff-only",
|
|
56
|
+
"prompt": "Inspect the repository, apply safe dependency updates, and explain every change you made.",
|
|
57
|
+
"qualityGate": "npm test",
|
|
58
|
+
"timeoutSeconds": 1800
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Mapping table:
|
|
63
|
+
|
|
64
|
+
| Cron concept | Scheduler equivalent |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| `cd /path && command` | `workingDirectory` or `workspaceId` |
|
|
67
|
+
| `>> file 2>&1` | log file is written automatically (`logs/<task>.log`) |
|
|
68
|
+
| `&&` chains | `beforeScript`, `prompt`, `qualityGate`, `afterScript` |
|
|
69
|
+
| exit code check | Quality Gate |
|
|
70
|
+
| `MAILTO` | webhook notifications |
|
|
71
|
+
| `%` escapes | not needed; write the prompt as normal text |
|
|
72
|
+
| `@reboot` | not supported; use a file/MCP trigger or a frequent cron |
|
|
73
|
+
|
|
74
|
+
Notes:
|
|
75
|
+
|
|
76
|
+
- `@daily`, `@hourly` and similar macros are not supported — write `0 0 * * *`,
|
|
77
|
+
`0 * * * *`, and so on.
|
|
78
|
+
- `@reboot` and `@yearly` have no direct equivalent.
|
|
79
|
+
- Cron environments are minimal. The wrapper inherits the user environment of the OS
|
|
80
|
+
scheduler entry, not your interactive shell. Absolute paths are safer than relying on
|
|
81
|
+
`PATH` from `.bashrc`.
|
|
82
|
+
|
|
83
|
+
## From systemd timers
|
|
84
|
+
|
|
85
|
+
The plugin schedules through the user crontab on Linux, so systemd calendar syntax is
|
|
86
|
+
translated to a cron expression when you migrate.
|
|
87
|
+
|
|
88
|
+
**Before**
|
|
89
|
+
|
|
90
|
+
```ini
|
|
91
|
+
# api-nightly.timer
|
|
92
|
+
[Timer]
|
|
93
|
+
OnCalendar=*-*-* 02:00:00
|
|
94
|
+
Persistent=true
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
```ini
|
|
98
|
+
# api-nightly.service
|
|
99
|
+
[Service]
|
|
100
|
+
WorkingDirectory=/srv/api
|
|
101
|
+
ExecStart=/usr/bin/npm run nightly
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**After**
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"name": "api-nightly",
|
|
109
|
+
"schedule": "0 2 * * *",
|
|
110
|
+
"workingDirectory": "/srv/api",
|
|
111
|
+
"prompt": "Run the nightly routine described in package.json and summarize the result.",
|
|
112
|
+
"qualityGate": "npm test"
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
| systemd | Scheduler |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `OnCalendar=*-*-* 02:00` | `0 2 * * *` |
|
|
119
|
+
| `OnUnitActiveSec=15min` | `*/15 * * * *` |
|
|
120
|
+
| `WorkingDirectory` | `workingDirectory` / `workspaceId` |
|
|
121
|
+
| `Environment=` | set it in the hook or in the user environment |
|
|
122
|
+
| `TimeoutStartSec` | `timeoutSeconds` |
|
|
123
|
+
| `Persistent=true` | catch-up is not implemented; a missed window is skipped |
|
|
124
|
+
| `Requires=` / `After=` | `dependsOn` |
|
|
125
|
+
|
|
126
|
+
Disable the old units (`systemctl --user disable --now api-nightly.timer`) only after
|
|
127
|
+
the new task has run successfully at least once.
|
|
128
|
+
|
|
129
|
+
## From launchd
|
|
130
|
+
|
|
131
|
+
**Before**
|
|
132
|
+
|
|
133
|
+
```xml
|
|
134
|
+
<key>StartCalendarInterval</key>
|
|
135
|
+
<dict><key>Hour</key><integer>2</integer></dict>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**After**
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"name": "mac-nightly",
|
|
143
|
+
"schedule": "0 2 * * *",
|
|
144
|
+
"workingDirectory": "/Users/me/projects/api",
|
|
145
|
+
"prompt": "Run the nightly maintenance and report anything unusual."
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| launchd | Scheduler |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| `StartCalendarInterval` | cron expression |
|
|
152
|
+
| `StartInterval` (seconds) | `*/N * * * *` (minute granularity) |
|
|
153
|
+
| `WorkingDirectory` | `workingDirectory` |
|
|
154
|
+
| `StandardOutPath` / `StandardErrorPath` | automatic log file |
|
|
155
|
+
| `RunAtLoad` | not supported; use a manual run or a file trigger |
|
|
156
|
+
|
|
157
|
+
## From Windows Task Scheduler
|
|
158
|
+
|
|
159
|
+
Existing tasks usually point to a `.bat`/`.ps1` file or a command line.
|
|
160
|
+
|
|
161
|
+
**After**
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"name": "win-nightly",
|
|
166
|
+
"schedule": "0 2 * * *",
|
|
167
|
+
"workingDirectory": "C:\\projects\\api",
|
|
168
|
+
"prompt": "Run the nightly maintenance for this repository.",
|
|
169
|
+
"qualityGate": "npm test"
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
| Task Scheduler | Scheduler |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| Trigger "Daily" | `0 2 * * *` |
|
|
176
|
+
| Trigger "At log on" | not supported; use a file trigger or a start-up hook |
|
|
177
|
+
| "Run whether user is logged on" | the plugin registers tasks in the current user context |
|
|
178
|
+
| "Stop task if it runs longer than" | `timeoutSeconds` |
|
|
179
|
+
| "If the task is already running" | lock file, the second run is `skipped` |
|
|
180
|
+
| Action "Start a program" | you describe the goal in a prompt instead of a command |
|
|
181
|
+
| Multiple actions | `beforeScript` + `prompt` + `qualityGate` + `afterScript` |
|
|
182
|
+
|
|
183
|
+
Delete the old task only after verifying the new one:
|
|
184
|
+
`schtasks /delete /tn "<old task>" /f`.
|
|
185
|
+
|
|
186
|
+
## From another scheduler plugin
|
|
187
|
+
|
|
188
|
+
There is no universal importer, because definition formats differ. The workflow is:
|
|
189
|
+
|
|
190
|
+
1. List the old jobs and copy their schedules, prompts and working directories.
|
|
191
|
+
2. Recreate them with `schedule_task` or the GUI.
|
|
192
|
+
3. If the old plugin exports JSON, transform it into the import format below and use
|
|
193
|
+
`import_tasks` — validation reports per-record errors.
|
|
194
|
+
4. Disable the old plugin before the first overlapping run.
|
|
195
|
+
|
|
196
|
+
## Bulk import and export
|
|
197
|
+
|
|
198
|
+
**Export format**
|
|
199
|
+
|
|
200
|
+
```json
|
|
201
|
+
{
|
|
202
|
+
"version": 1,
|
|
203
|
+
"exportedAt": "2026-01-01T00:00:00.000Z",
|
|
204
|
+
"tasks": [
|
|
205
|
+
{
|
|
206
|
+
"name": "api-nightly",
|
|
207
|
+
"schedule": "0 2 * * *",
|
|
208
|
+
"prompt": "Nightly maintenance.",
|
|
209
|
+
"qualityGate": "npm test",
|
|
210
|
+
"workspaceId": "ws-api"
|
|
211
|
+
}
|
|
212
|
+
]
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
**Import**
|
|
217
|
+
|
|
218
|
+
Use `import_tasks` from the GUI or the RPC layer. Rules:
|
|
219
|
+
|
|
220
|
+
- `name` and `prompt` are required.
|
|
221
|
+
- `cron` tasks need a schedule; `file` tasks need `watchPath`; `mcp-event` tasks need
|
|
222
|
+
`mcpEvent.event`.
|
|
223
|
+
- Matrix tasks cannot also set `workspaceId`, and `matrix.workspaceIds` must not be
|
|
224
|
+
empty.
|
|
225
|
+
- Workspace ids must exist in the target installation, or the record is rejected.
|
|
226
|
+
- Errors are reported per record; valid records are imported.
|
|
227
|
+
|
|
228
|
+
Workspaces are not exported as directories — recreate them with
|
|
229
|
+
`manage_workspaces` first, then map old paths by hand.
|
|
230
|
+
|
|
231
|
+
## Verification checklist
|
|
232
|
+
|
|
233
|
+
For every migrated job:
|
|
234
|
+
|
|
235
|
+
1. `dry_run` with the task name — check order, dependencies and estimated time.
|
|
236
|
+
2. `run_task_now` — confirm the log shows the expected work.
|
|
237
|
+
3. Check the Quality Gate result in `get_history`.
|
|
238
|
+
4. Confirm the next scheduled run appears with a correct "next run" timestamp.
|
|
239
|
+
5. For matrix jobs, expand the parent in the dashboard and verify every clone has the
|
|
240
|
+
right workspace path.
|
|
241
|
+
6. Wait for at least one natural scheduled run before deleting the old definition.
|
|
242
|
+
|
|
243
|
+
## Common pitfalls
|
|
244
|
+
|
|
245
|
+
| Symptom | Cause | Fix |
|
|
246
|
+
| --- | --- | --- |
|
|
247
|
+
| `skipped` in history | previous run still holds the lock | wait, or lower `timeoutSeconds` |
|
|
248
|
+
| `timeout` every run | the agent needs more time | raise `timeoutSeconds` |
|
|
249
|
+
| Quality Gate fails but the work looks fine | gate runs in the task directory, not a subdirectory | prefix the command with `cd subdir && ...` |
|
|
250
|
+
| Agent cannot find the project | no `workingDirectory`/`workspaceId`, so it ran in the plugin directory | set the working directory |
|
|
251
|
+
| "Workspace path does not exist" on import | workspace ids belong to another machine | recreate workspaces and remap ids |
|
|
252
|
+
| Two runs at once after migration | old scheduler is still enabled | disable the old job |
|
|
253
|
+
| Cron rejected | expression not expressible by `schtasks` | use a supported pattern (`*/N`, fixed minute/hour, weekdays) |
|
|
254
|
+
| Prompts behave differently at night | interactive shell environment vs scheduler environment | use absolute paths, avoid alias-dependent commands |
|
|
255
|
+
|
|
256
|
+
## Rollback
|
|
257
|
+
|
|
258
|
+
If something goes wrong:
|
|
259
|
+
|
|
260
|
+
1. Re-enable the old jobs (they were never deleted).
|
|
261
|
+
2. `pause_task` the migrated ones, or delete them.
|
|
262
|
+
3. Export the plugin definitions before major changes: `export_tasks` gives a single
|
|
263
|
+
JSON file you can re-import on any machine.
|
|
264
|
+
|
|
265
|
+
Definitions live in `scheduler.db`; deleting the plugin directory removes all state.
|
|
266
|
+
Export first if you might want it back.
|
|
Binary file
|