agent-steward 0.0.0-stage → 0.0.2
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 +376 -0
- package/CROSS_PLATFORM.md +149 -0
- package/LICENSE +21 -0
- package/README.md +314 -2
- package/ROADMAP-STRATEGY.md +147 -0
- package/ROADMAP.md +1069 -0
- package/dist/core/analytics.d.ts +132 -0
- package/dist/core/analytics.d.ts.map +1 -0
- package/dist/core/analytics.js +290 -0
- package/dist/core/audit.d.ts +96 -0
- package/dist/core/audit.d.ts.map +1 -0
- package/dist/core/audit.js +297 -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 +250 -0
- package/dist/core/dry-run.d.ts +102 -0
- package/dist/core/dry-run.d.ts.map +1 -0
- package/dist/core/dry-run.js +447 -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 +186 -0
- package/dist/core/git-trigger.d.ts +82 -0
- package/dist/core/git-trigger.d.ts.map +1 -0
- package/dist/core/git-trigger.js +312 -0
- package/dist/core/glob.d.ts +38 -0
- package/dist/core/glob.d.ts.map +1 -0
- package/dist/core/glob.js +233 -0
- package/dist/core/local-ai.d.ts +52 -0
- package/dist/core/local-ai.d.ts.map +1 -0
- package/dist/core/local-ai.js +119 -0
- package/dist/core/lock.d.ts +57 -0
- package/dist/core/lock.d.ts.map +1 -0
- package/dist/core/lock.js +195 -0
- package/dist/core/matrix.d.ts +167 -0
- package/dist/core/matrix.d.ts.map +1 -0
- package/dist/core/matrix.js +724 -0
- package/dist/core/native-notify.d.ts +36 -0
- package/dist/core/native-notify.d.ts.map +1 -0
- package/dist/core/native-notify.js +113 -0
- package/dist/core/one-shot.d.ts +68 -0
- package/dist/core/one-shot.d.ts.map +1 -0
- package/dist/core/one-shot.js +139 -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/permissions.d.ts +69 -0
- package/dist/core/permissions.d.ts.map +1 -0
- package/dist/core/permissions.js +143 -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 +73 -0
- package/dist/core/ps-wrapper.d.ts.map +1 -0
- package/dist/core/ps-wrapper.js +1071 -0
- package/dist/core/record-history.d.ts +25 -0
- package/dist/core/record-history.d.ts.map +1 -0
- package/dist/core/record-history.js +471 -0
- package/dist/core/retention.d.ts +29 -0
- package/dist/core/retention.d.ts.map +1 -0
- package/dist/core/retention.js +98 -0
- package/dist/core/savings.d.ts +70 -0
- package/dist/core/savings.d.ts.map +1 -0
- package/dist/core/savings.js +87 -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 +211 -0
- package/dist/core/schedule-v2.d.ts +116 -0
- package/dist/core/schedule-v2.d.ts.map +1 -0
- package/dist/core/schedule-v2.js +586 -0
- package/dist/core/scheduler/index.d.ts +32 -0
- package/dist/core/scheduler/index.d.ts.map +1 -0
- package/dist/core/scheduler/index.js +63 -0
- package/dist/core/scheduler/linux.d.ts +44 -0
- package/dist/core/scheduler/linux.d.ts.map +1 -0
- package/dist/core/scheduler/linux.js +225 -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 +40 -0
- package/dist/core/scheduler/mac.d.ts.map +1 -0
- package/dist/core/scheduler/mac.js +207 -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 +89 -0
- package/dist/core/scheduler/registry.d.ts +41 -0
- package/dist/core/scheduler/registry.d.ts.map +1 -0
- package/dist/core/scheduler/registry.js +57 -0
- package/dist/core/scheduler/types.d.ts +86 -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 +99 -0
- package/dist/core/scheduler/windows.d.ts.map +1 -0
- package/dist/core/scheduler/windows.js +596 -0
- package/dist/core/secrets.d.ts +66 -0
- package/dist/core/secrets.d.ts.map +1 -0
- package/dist/core/secrets.js +433 -0
- package/dist/core/self-analysis.d.ts +117 -0
- package/dist/core/self-analysis.d.ts.map +1 -0
- package/dist/core/self-analysis.js +539 -0
- package/dist/core/self-analysis.test.d.ts +2 -0
- package/dist/core/self-analysis.test.d.ts.map +1 -0
- package/dist/core/self-analysis.test.js +219 -0
- package/dist/core/session.d.ts +42 -0
- package/dist/core/session.d.ts.map +1 -0
- package/dist/core/session.js +134 -0
- package/dist/core/shutdown.d.ts +26 -0
- package/dist/core/shutdown.d.ts.map +1 -0
- package/dist/core/shutdown.js +49 -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 +146 -0
- package/dist/core/summary.d.ts +69 -0
- package/dist/core/summary.d.ts.map +1 -0
- package/dist/core/summary.js +250 -0
- package/dist/core/telegram.d.ts +55 -0
- package/dist/core/telegram.d.ts.map +1 -0
- package/dist/core/telegram.js +344 -0
- package/dist/core/triage-chain.d.ts +40 -0
- package/dist/core/triage-chain.d.ts.map +1 -0
- package/dist/core/triage-chain.js +80 -0
- package/dist/core/triage-compare.d.ts +68 -0
- package/dist/core/triage-compare.d.ts.map +1 -0
- package/dist/core/triage-compare.js +184 -0
- package/dist/core/triage-rules.d.ts +23 -0
- package/dist/core/triage-rules.d.ts.map +1 -0
- package/dist/core/triage-rules.js +196 -0
- package/dist/core/triage-shadow.d.ts +91 -0
- package/dist/core/triage-shadow.d.ts.map +1 -0
- package/dist/core/triage-shadow.js +160 -0
- package/dist/core/triage-worker.d.ts +55 -0
- package/dist/core/triage-worker.d.ts.map +1 -0
- package/dist/core/triage-worker.js +314 -0
- package/dist/core/triage.d.ts +76 -0
- package/dist/core/triage.d.ts.map +1 -0
- package/dist/core/triage.js +271 -0
- package/dist/core/watch-paths.d.ts +6 -0
- package/dist/core/watch-paths.d.ts.map +1 -0
- package/dist/core/watch-paths.js +62 -0
- package/dist/core/wrappers/bash.d.ts +95 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -0
- package/dist/core/wrappers/bash.js +413 -0
- package/dist/db/git-state-repo.d.ts +16 -0
- package/dist/db/git-state-repo.d.ts.map +1 -0
- package/dist/db/git-state-repo.js +38 -0
- package/dist/db/history-repo.d.ts +110 -0
- package/dist/db/history-repo.d.ts.map +1 -0
- package/dist/db/history-repo.js +300 -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 +46 -0
- package/dist/db/metrics-repo.d.ts.map +1 -0
- package/dist/db/metrics-repo.js +103 -0
- package/dist/db/migrate.d.ts +24 -0
- package/dist/db/migrate.d.ts.map +1 -0
- package/dist/db/migrate.js +244 -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 +170 -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 +60 -0
- package/dist/history.d.ts.map +1 -0
- package/dist/history.js +70 -0
- package/dist/i18n.d.ts +75 -0
- package/dist/i18n.d.ts.map +1 -0
- package/dist/i18n.js +357 -0
- package/dist/index.d.ts +858 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5179 -0
- package/dist/integrations.d.ts +72 -0
- package/dist/integrations.d.ts.map +1 -0
- package/dist/integrations.js +233 -0
- package/dist/notifications.d.ts +199 -0
- package/dist/notifications.d.ts.map +1 -0
- package/dist/notifications.js +967 -0
- package/dist/profiles.d.ts +60 -0
- package/dist/profiles.d.ts.map +1 -0
- package/dist/profiles.js +227 -0
- package/dist/rpc.d.ts +3806 -0
- package/dist/rpc.d.ts.map +1 -0
- package/dist/rpc.js +1507 -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 +128 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +2413 -0
- package/dist/settings.d.ts +389 -0
- package/dist/settings.d.ts.map +1 -0
- package/dist/settings.js +770 -0
- package/dist/shared/jobs-view.d.ts +59 -0
- package/dist/shared/jobs-view.d.ts.map +1 -0
- package/dist/shared/jobs-view.js +146 -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 +252 -0
- package/dist/task-transfer.d.ts.map +1 -0
- package/dist/task-transfer.js +628 -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 +96 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +130 -0
- package/dist/version.d.ts +8 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +27 -0
- package/dist/workspaces.d.ts +113 -0
- package/dist/workspaces.d.ts.map +1 -0
- package/dist/workspaces.js +393 -0
- package/docs/ARCHITECTURE.md +457 -0
- package/docs/COMPATIBILITY.md +233 -0
- package/docs/CONCEPT.md +230 -0
- package/docs/CROSS_PLATFORM.ru.md +150 -0
- package/docs/CROSS_PLATFORM.zh.md +146 -0
- package/docs/FAQ.md +52 -0
- package/docs/FAQ.ru.md +53 -0
- package/docs/FAQ.zh.md +43 -0
- package/docs/FEATURES.md +698 -0
- package/docs/FEATURES.zh.md +655 -0
- package/docs/LOCAL-AI.md +300 -0
- package/docs/MIGRATION.md +355 -0
- package/docs/README.ru.md +268 -0
- package/docs/README.zh.md +305 -0
- package/docs/SAVINGS.md +61 -0
- package/docs/SAVINGS.ru.md +60 -0
- package/docs/SAVINGS.zh.md +52 -0
- package/docs/V1-V2-COMPATIBILITY-PLAN.md +366 -0
- package/docs/ZH-LOCALE-PLAN.md +324 -0
- package/docs/dashboard.png +0 -0
- package/docs/spikes/local-model-structured-output.md +81 -0
- package/docs/spikes/ollama-qwen3-4b-smoke.json +28 -0
- package/docs/spikes/ollama-qwen3-4b.json +163 -0
- package/gui-experimental.cjs +9 -0
- package/index.js +1 -0
- package/locales/en.json +780 -0
- package/locales/ru.json +780 -0
- package/locales/zh.json +780 -0
- package/package.json +149 -4
- package/scripts/bench-local.mjs +321 -0
- package/scripts/check-zh-locale.mjs +218 -0
- package/scripts/demo-dashboard.mjs +209 -0
- package/scripts/run-tests.mjs +236 -0
- package/scripts/spike-local-structured.mjs +182 -0
- package/scripts/test-locale.mjs +45 -0
- package/skills/scheduled-job-best-practices/SKILL.md +158 -0
- package/skills/scheduled-job-best-practices/references/recipes.md +163 -0
- package/src/core/analytics.ts +424 -0
- package/src/core/audit.ts +418 -0
- package/src/core/cron-to-schtasks.ts +288 -0
- package/src/core/dry-run.ts +601 -0
- package/src/core/file-watcher.ts +245 -0
- package/src/core/git-trigger.ts +391 -0
- package/src/core/glob.ts +226 -0
- package/src/core/local-ai.ts +173 -0
- package/src/core/lock.ts +219 -0
- package/src/core/matrix.ts +947 -0
- package/src/core/native-notify.ts +157 -0
- package/src/core/one-shot.ts +189 -0
- package/src/core/otel.ts +128 -0
- package/src/core/permissions.ts +200 -0
- package/src/core/prometheus.ts +215 -0
- package/src/core/ps-wrapper.ts +1140 -0
- package/src/core/record-history.ts +615 -0
- package/src/core/retention.ts +141 -0
- package/src/core/savings.ts +150 -0
- package/src/core/schedule-gate.ts +253 -0
- package/src/core/schedule-v2.ts +668 -0
- package/src/core/scheduler/index.ts +82 -0
- package/src/core/scheduler/linux.ts +257 -0
- package/src/core/scheduler/logs.ts +37 -0
- package/src/core/scheduler/mac.ts +270 -0
- package/src/core/scheduler/posix.ts +114 -0
- package/src/core/scheduler/registry.ts +99 -0
- package/src/core/scheduler/types.ts +90 -0
- package/src/core/scheduler/windows.ts +711 -0
- package/src/core/secrets.ts +503 -0
- package/src/core/self-analysis.ts +744 -0
- package/src/core/session.ts +150 -0
- package/src/core/shutdown.ts +69 -0
- package/src/core/structured-log.ts +214 -0
- package/src/core/summary.ts +318 -0
- package/src/core/telegram.ts +436 -0
- package/src/core/triage-chain.ts +125 -0
- package/src/core/triage-compare.ts +277 -0
- package/src/core/triage-rules.ts +238 -0
- package/src/core/triage-shadow.ts +240 -0
- package/src/core/triage-worker.ts +344 -0
- package/src/core/triage.ts +366 -0
- package/src/core/watch-paths.ts +70 -0
- package/src/core/wrappers/bash.ts +532 -0
- package/src/db/git-state-repo.ts +62 -0
- package/src/db/history-repo.ts +492 -0
- package/src/db/index.ts +166 -0
- package/src/db/metrics-repo.ts +170 -0
- package/src/db/migrate.ts +328 -0
- package/src/db/recovery.ts +46 -0
- package/src/db/schema.ts +188 -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 +5222 -0
- package/src/history.ts +128 -0
- package/src/i18n.ts +413 -0
- package/src/index.ts +6605 -0
- package/src/integrations.ts +297 -0
- package/src/notifications.ts +1346 -0
- package/src/profiles.ts +254 -0
- package/src/rpc.ts +1609 -0
- package/src/schtasks.ts +75 -0
- package/src/server.ts +2662 -0
- package/src/settings.ts +1369 -0
- package/src/shared/jobs-view.ts +188 -0
- package/src/skill.ts +113 -0
- package/src/task-transfer.ts +944 -0
- package/src/templates.ts +67 -0
- package/src/tui-v1.tsx +341 -0
- package/src/tui.tsx +329 -0
- package/src/types.ts +191 -0
- package/src/version.ts +27 -0
- package/src/workspaces.ts +487 -0
package/docs/FEATURES.md
ADDED
|
@@ -0,0 +1,698 @@
|
|
|
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
|
+
Translations: [中文](FEATURES.zh.md).
|
|
7
|
+
|
|
8
|
+
- [Scheduling](#scheduling)
|
|
9
|
+
- [Execution policy](#execution-policy)
|
|
10
|
+
- [Orchestration](#orchestration)
|
|
11
|
+
- [Multi-repository workspaces](#multi-repository-workspaces)
|
|
12
|
+
- [Profiles (multi-project)](#profiles-multi-project-sprint-21)
|
|
13
|
+
- [Workspace environment variables](#workspace-environment-variables-sprint-21)
|
|
14
|
+
- [Observability](#observability)
|
|
15
|
+
- [Management](#management)
|
|
16
|
+
- [Agent interface](#agent-interface)
|
|
17
|
+
- [Platform support](#platform-support)
|
|
18
|
+
- [Limits and non-goals](#limits-and-non-goals)
|
|
19
|
+
|
|
20
|
+
## Scheduling
|
|
21
|
+
|
|
22
|
+
### Cron schedules
|
|
23
|
+
|
|
24
|
+
Five-field cron: `minute hour day-of-month month day-of-week`. Supports lists,
|
|
25
|
+
ranges and steps in every field (`0 8-10,18 * * 1-5/2`), month and weekday names
|
|
26
|
+
(`0 9 * * MON-FRI`), `@every` sugar (`@every 15m`, `@every 2h`, `@every 1d`),
|
|
27
|
+
`L` as the last day of the month and the `d#n` n-th weekday form (`0 9 * * FRI#3`).
|
|
28
|
+
|
|
29
|
+
| Pattern | Example | Meaning |
|
|
30
|
+
| --- | --- | --- |
|
|
31
|
+
| Every N minutes | `*/15 * * * *` | Every 15 minutes |
|
|
32
|
+
| Fixed time | `0 9 * * *` | Daily at 09:00 |
|
|
33
|
+
| Weekdays | `30 8 * * 1-5` | 08:30 Monday to Friday |
|
|
34
|
+
| Monthly | `0 3 1 * *` | 03:00 on the 1st |
|
|
35
|
+
| Last day | `0 3 L * *` | 03:00 on the last day of the month |
|
|
36
|
+
| N-th weekday | `0 9 * * FRI#3` | 09:00 on the third Friday |
|
|
37
|
+
| Sugar | `@every 15m` | Every 15 minutes |
|
|
38
|
+
|
|
39
|
+
The Windows backend translates simple cron expressions to native Task Scheduler
|
|
40
|
+
triggers. Expressions `schtasks` cannot express (`L`, `#`, complex lists) or tasks
|
|
41
|
+
with a timezone other than the system one are registered in poll mode: the OS task
|
|
42
|
+
wakes the wrapper every minute and `schedule-gate` decides whether the agent runs.
|
|
43
|
+
|
|
44
|
+
### One-shot runs
|
|
45
|
+
|
|
46
|
+
`triggerType: "once"` runs a task exactly once at a specific moment. Use either
|
|
47
|
+
`runAt` (ISO-8601, or a local date string such as `2026-11-13 22:40`) or
|
|
48
|
+
`delaySeconds` (delay from now):
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"name": "deploy-once",
|
|
53
|
+
"triggerType": "once",
|
|
54
|
+
"runAt": "2026-11-13T22:40:00+03:00",
|
|
55
|
+
"prompt": "Deploy the current main branch."
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{ "name": "remind-later", "triggerType": "once", "delaySeconds": 3600, "prompt": "..." }
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`runAt` wins when both are present. `schedule` is ignored. One-shot tasks are
|
|
64
|
+
registered natively (`schtasks /sc ONCE`, Linux `at`, macOS launchd cleanup
|
|
65
|
+
agent), are not repeated after a plugin restart, and cannot be combined with a
|
|
66
|
+
|
|
67
|
+
> **Windows locale note.** `schtasks /sd` only accepts dates in the format of the
|
|
68
|
+
> current Windows locale. The plugin emits `DD.MM.YYYY`, which matches Russian
|
|
69
|
+
> (and most European) locales. On a system with an English/US locale (`MM/DD/YYYY`)
|
|
70
|
+
> `schtasks` rejects the date, so one-shot tasks are not available there.
|
|
71
|
+
matrix.
|
|
72
|
+
|
|
73
|
+
### Session continuity
|
|
74
|
+
|
|
75
|
+
Each scheduled run can either start a fresh OpenCode session (`new`, default),
|
|
76
|
+
reuse a persistent session stored on the task, or continue the latest session
|
|
77
|
+
(`last`, mapped to `opencode --continue`). Set `session` on the task; for
|
|
78
|
+
`reuse` a `sessionId` is auto-generated and stored with the task definition —
|
|
79
|
+
it is never accepted from user input or exported as plain text.
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{
|
|
83
|
+
"name": "nightly-analyst",
|
|
84
|
+
"schedule": "0 3 * * *",
|
|
85
|
+
"session": "reuse",
|
|
86
|
+
"sessionMaxRuns": 10,
|
|
87
|
+
"prompt": "Refresh the analysis."
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- `session`: `new` (default), `reuse` (pass `--session <id>`), `last` (pass `--continue`).
|
|
92
|
+
- `sessionMaxRuns` (only for `reuse`): how many runs the reused session
|
|
93
|
+
survives before it is deleted (`opencode session delete`) and a fresh session
|
|
94
|
+
is started. Unset/0 means no limit.
|
|
95
|
+
- `sessionId` is per machine/profile. The internal run counter
|
|
96
|
+
(`sessionRunCount`) is never exported.
|
|
97
|
+
- Old export/import files without session fields import as `new`.
|
|
98
|
+
|
|
99
|
+
### Timezones and launch windows
|
|
100
|
+
|
|
101
|
+
- `timezone` — IANA zone per task (e.g. `Europe/Moscow`). `nextRun`/`prevRun`,
|
|
102
|
+
dry-run next-run estimates and the gate evaluate cron in this zone; DST
|
|
103
|
+
transitions are handled (nonexistent spring-forward times are skipped).
|
|
104
|
+
- `notBefore` / `notAfter` — daily launch window in `HH:MM` (may cross midnight,
|
|
105
|
+
e.g. `22:00`–`06:00`). A run that fires outside the window is **postponed**
|
|
106
|
+
until the window opens (once, via a defer-file), not skipped.
|
|
107
|
+
- `activeDays` — allowed weekdays `0`=Sunday … `6`=Saturday (Sprint 27). Empty or
|
|
108
|
+
all seven means every day. Applies to cron and event triggers.
|
|
109
|
+
- `windowPolicy` — behaviour outside the window or on a disallowed day (Sprint 27):
|
|
110
|
+
`postpone` (default) waits for the next opening (max 12 hours), `skip` drops the
|
|
111
|
+
run, `run` executes anyway.
|
|
112
|
+
- `pausedUntil` — pause a task until an ISO moment. `pause_task` accepts
|
|
113
|
+
`until`; the plugin re-enables the task automatically at startup and on a
|
|
114
|
+
5-minute timer, and `resume_task` resumes early.
|
|
115
|
+
|
|
116
|
+
### File triggers
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"name": "regen-api-client",
|
|
121
|
+
"triggerType": "file",
|
|
122
|
+
"watchPath": "C:\\projects\\api\\openapi.yaml",
|
|
123
|
+
"prompt": "Regenerate the API client from openapi.yaml and run contract tests."
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The file is watched with chokidar in the plugin host, changes are debounced. File
|
|
128
|
+
triggers ignore `schedule`.
|
|
129
|
+
|
|
130
|
+
#### Glob masks for file triggers (Sprint 27)
|
|
131
|
+
|
|
132
|
+
`watchGlobs` and `watchIgnore` restrict which changes count as a trigger:
|
|
133
|
+
|
|
134
|
+
Masks support `*` (does not cross `/`), `**` (any segments, including zero),
|
|
135
|
+
`?` (one character), `[abc]` / `[a-z]` (classes), `{a,b}` (alternatives) and `!`
|
|
136
|
+
(negation). Empty `watchGlobs` means "any change". Paths are normalized to POSIX
|
|
137
|
+
form (`\` → `/`), comparison is case-insensitive on Windows.
|
|
138
|
+
|
|
139
|
+
### Git triggers (Sprint 27)
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"name": "deploy-on-push",
|
|
144
|
+
"triggerType": "git",
|
|
145
|
+
"workingDirectory": "C:\\projects\\api",
|
|
146
|
+
"gitBranch": "main, release/*",
|
|
147
|
+
"gitPaths": ["src/**", "package.json"],
|
|
148
|
+
"gitIgnore": ["**/*.md", "CHANGELOG.md"],
|
|
149
|
+
"gitPollSeconds": 60,
|
|
150
|
+
"prompt": "Deploy the changed services to staging."
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
A task with `triggerType: "git"` starts when a new commit appears in its working
|
|
155
|
+
directory. The first poll only remembers the current `HEAD` (baseline) and does not
|
|
156
|
+
start anything. Later polls compare `git diff --name-only <last>..HEAD` and start
|
|
157
|
+
the task when masks `gitPaths` (empty — any file) match and are not excluded by
|
|
158
|
+
`gitIgnore`. Filter `gitBranch` limits branches (comma-separated, supports `*` and `?`).
|
|
159
|
+
|
|
160
|
+
Poll period `gitPollSeconds` — minimum 5 seconds, default 60. State (the last
|
|
161
|
+
processed commit) is stored in SQLite table `git_state`, so a plugin restart does
|
|
162
|
+
not cause repeated runs.
|
|
163
|
+
|
|
164
|
+
### MCP event triggers
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"name": "on-pr-opened",
|
|
169
|
+
"triggerType": "mcp-event",
|
|
170
|
+
"mcpEvent": { "server": "github", "event": "pull_request.opened", "filter": "repo=acme/api" },
|
|
171
|
+
"prompt": "Review the newly opened pull request."
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Events are emitted through the `emit_event` RPC method.
|
|
176
|
+
|
|
177
|
+
### Manual runs and pause
|
|
178
|
+
|
|
179
|
+
- `run_task_now` starts a task immediately, through the same wrapper (timeout, lock,
|
|
180
|
+
hooks, Quality Gate).
|
|
181
|
+
- `pause_task` / `resume_task` disable and re-enable the OS entry. For a matrix parent
|
|
182
|
+
every clone is paused.
|
|
183
|
+
|
|
184
|
+
### Logon mode (Windows)
|
|
185
|
+
|
|
186
|
+
By default a task is **interactive only**: Task Scheduler runs it only while the user
|
|
187
|
+
who created it is logged on. That is the safe default — the job sees the user profile,
|
|
188
|
+
mapped drives, the project's `opencode.json` and saved credentials.
|
|
189
|
+
|
|
190
|
+
Some jobs must run outside business hours or on a locked/signed-out machine. Pass
|
|
191
|
+
`runWhenLoggedOff: true` (agent tool `schedule_task` / `update_task`, or the sidebar) to
|
|
192
|
+
register the task as `schtasks /ru SYSTEM` instead. The run then happens in session 0,
|
|
193
|
+
without the user's profile, mapped drives, network shares or saved credentials. Tasks
|
|
194
|
+
that depend on the user environment can fail with `Access is denied` or missing files,
|
|
195
|
+
so check them with `dry_run` first and prefer absolute paths.
|
|
196
|
+
|
|
197
|
+
`runWhenLoggedOff` is Windows-only: Linux crontab already runs without a logged-on user,
|
|
198
|
+
and a macOS launchd agent runs only inside a user session. `list_tasks` reports both the
|
|
199
|
+
OS value (`logonMode`) and the plugin setting (`runWhenLoggedOff`); `dry_run` shows the
|
|
200
|
+
same pair before the task is registered.
|
|
201
|
+
|
|
202
|
+
## Execution policy
|
|
203
|
+
|
|
204
|
+
### Timeout and no-overlap
|
|
205
|
+
|
|
206
|
+
Every run has `timeoutSeconds` (default 3600). On expiry the process tree is stopped
|
|
207
|
+
and the run is recorded as `timeout`. A lock file prevents two runs of the same task
|
|
208
|
+
from overlapping; the second start exits immediately and is recorded as `skipped`.
|
|
209
|
+
|
|
210
|
+
### Pre-flight, Quality Gate, post-flight
|
|
211
|
+
|
|
212
|
+
```json
|
|
213
|
+
{
|
|
214
|
+
"name": "nightly-deps",
|
|
215
|
+
"schedule": "0 2 * * *",
|
|
216
|
+
"beforeScript": "git pull --ff-only",
|
|
217
|
+
"prompt": "Update dependencies, fix breaking changes, keep the diff minimal.",
|
|
218
|
+
"qualityGate": "npm test",
|
|
219
|
+
"afterScript": "git push",
|
|
220
|
+
"timeoutSeconds": 2400
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
| Hook | When | Effect of non-zero exit |
|
|
225
|
+
| --- | --- | --- |
|
|
226
|
+
| `beforeScript` | before the agent starts | run is cancelled, pre-flight marked failed |
|
|
227
|
+
| `qualityGate` | after a successful response | run is marked as a Quality Gate failure (error) |
|
|
228
|
+
| `afterScript` | after the run, even on failure | reported in history, does not rewrite a success |
|
|
229
|
+
|
|
230
|
+
### Retries
|
|
231
|
+
|
|
232
|
+
`retryCount` and `retryDelay` (seconds) retry a failed run. Retry state is persisted,
|
|
233
|
+
so a crash cannot produce an infinite retry loop. Retries happen before chains and
|
|
234
|
+
dependents.
|
|
235
|
+
|
|
236
|
+
### Model and priority
|
|
237
|
+
|
|
238
|
+
`model` selects an OpenCode model (for example `anthropic/claude-3-5-sonnet`);
|
|
239
|
+
omitting it uses the OpenCode default. `priority` is `0..10` and is passed through to
|
|
240
|
+
the scheduler entry.
|
|
241
|
+
|
|
242
|
+
### Tool restrictions
|
|
243
|
+
|
|
244
|
+
The baseline comes from `permissions.defaultPolicy`: `hybrid` (default) allows
|
|
245
|
+
read/edit/glob/grep/subagent/skill/webfetch/websearch and denies `shell` and `question`,
|
|
246
|
+
`secure` allows only read/glob/grep/skill, and `legacy` restores the 1.5.x behaviour that
|
|
247
|
+
allowed everything. Task-level `legacyShell: true` re-enables `shell` under `hybrid` for
|
|
248
|
+
jobs migrated from older versions; `legacy` is the blunt alternative.
|
|
249
|
+
|
|
250
|
+
`allowedTools` and `deniedTools` are enforced for the `opencode run` process that the
|
|
251
|
+
task wrapper starts. The wrapper passes the generated `permissions` rules to the
|
|
252
|
+
process through `OPENCODE_CONFIG_CONTENT`; no file is written to the task workdir, so a
|
|
253
|
+
project-level `opencode.jsonc` is never overwritten. Each `deniedTools` entry becomes an
|
|
254
|
+
`effect: "deny"` rule for the matching OpenCode action, and `allowedTools` (when set)
|
|
255
|
+
denies every action that is not listed. The wrapper runs `opencode` with `--auto`, so
|
|
256
|
+
only non-denied permissions are auto-approved. Restrictions apply to the agent process,
|
|
257
|
+
not to hooks, Quality Gates or scripts, which still run with your user privileges. See
|
|
258
|
+
[ARCHITECTURE.md](ARCHITECTURE.md#permission-enforcement--known-limitations-spike-291-findings)
|
|
259
|
+
for the exact action mapping and known limitations (project/system config, nested
|
|
260
|
+
subagents).
|
|
261
|
+
|
|
262
|
+
## Orchestration
|
|
263
|
+
|
|
264
|
+
### Chains
|
|
265
|
+
|
|
266
|
+
```json
|
|
267
|
+
{ "name": "build", "nextTaskOnSuccess": "deploy", "nextTaskOnError": "notify-failure" }
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Exactly one follow-up task is started after a run.
|
|
271
|
+
|
|
272
|
+
### DAG dependencies
|
|
273
|
+
|
|
274
|
+
```json
|
|
275
|
+
{ "name": "smoke-tests", "dependsOn": ["deploy"], "schedule": "0 * * * *" }
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
A dependent starts only when every dependency's latest run is successful. If a
|
|
279
|
+
dependency is a matrix, **all clones** must be successful — a `partial` matrix blocks
|
|
280
|
+
dependents.
|
|
281
|
+
|
|
282
|
+
### Matrix builds (fan-out)
|
|
283
|
+
|
|
284
|
+
One definition, one clone per workspace:
|
|
285
|
+
|
|
286
|
+
```json
|
|
287
|
+
{
|
|
288
|
+
"name": "deploy",
|
|
289
|
+
"schedule": "0 3 * * *",
|
|
290
|
+
"prompt": "Build, test and deploy this repository. Report what changed.",
|
|
291
|
+
"matrix": {
|
|
292
|
+
"workspaceIds": ["ws-frontend", "ws-backend", "ws-mobile"],
|
|
293
|
+
"strategy": "parallel",
|
|
294
|
+
"failureMode": "continue",
|
|
295
|
+
"concurrency": 2,
|
|
296
|
+
"overrides": {
|
|
297
|
+
"ws-mobile": { "qualityGate": "flutter test", "prompt": "Use the Flutter toolchain." }
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
| Field | Default | Meaning |
|
|
304
|
+
| --- | --- | --- |
|
|
305
|
+
| `strategy` | `parallel` | `sequential` starts the next clone only after the previous one finishes |
|
|
306
|
+
| `failureMode` | `continue` | `stop` aborts the remaining clones after the first failure |
|
|
307
|
+
| `concurrency` | unlimited | Maximum clones running at once (ignored for `sequential`) |
|
|
308
|
+
| `aggregation` | `summary` | `summary` writes one aggregate record for the parent |
|
|
309
|
+
| `createAggregator` | `false` | Also create `<parent>-matrix-complete` depending on every clone |
|
|
310
|
+
| `overrides` | none | Per-workspace prompt/model/Quality Gate/hooks |
|
|
311
|
+
|
|
312
|
+
Behavior worth knowing:
|
|
313
|
+
|
|
314
|
+
- Clones are named `<parent>-matrix-<workspace>`, inherit the parent definition and get
|
|
315
|
+
their own working directory.
|
|
316
|
+
- The parent never runs itself; its status is the aggregate: `success`, `error`,
|
|
317
|
+
`partial` (some clones failed under `continue`), or `running`.
|
|
318
|
+
- Editing the parent (workspaces, prompt, overrides, concurrency) **syncs** the clone
|
|
319
|
+
set: missing clones are created, changed ones updated, removed ones deleted. Clones
|
|
320
|
+
with a running job are never touched.
|
|
321
|
+
- Cancelling a matrix (`matrix_control` with `action: "cancel"`) marks pending clones
|
|
322
|
+
as cancelled and stops running ones. Deleting a parent deletes its whole family.
|
|
323
|
+
- `matrix_control` with `action: "cleanup"` removes orphaned clones whose parent is
|
|
324
|
+
gone; the same cleanup also runs at plugin startup.
|
|
325
|
+
|
|
326
|
+
## Multi-repository workspaces
|
|
327
|
+
|
|
328
|
+
A workspace is a named directory: id, name, path, optional git remote and color.
|
|
329
|
+
|
|
330
|
+
```json
|
|
331
|
+
{ "id": "ws-api", "name": "API", "path": "C:\\projects\\api", "color": "#3b82f6" }
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
Use `workspaceId` instead of `workingDirectory` to run a task in a workspace. Paths are
|
|
335
|
+
validated on add/update/import, and the dashboard groups tasks and runs by workspace.
|
|
336
|
+
Workspaces are the unit that matrix builds fan out to.
|
|
337
|
+
|
|
338
|
+
## Profiles (multi-project, Sprint 21)
|
|
339
|
+
|
|
340
|
+
Profiles let you run several independent scheduler installations inside one plugin,
|
|
341
|
+
each with its own SQLite database, settings, logs, wrappers and dashboard port.
|
|
342
|
+
This is useful for separating projects, clients or environments (e.g. `default` and
|
|
343
|
+
`work`) without them seeing each other's data.
|
|
344
|
+
|
|
345
|
+
- Profile `default` uses the plugin's base directory (no migration, behaves exactly
|
|
346
|
+
as before Sprint 21). Named profiles live in `<base>/profiles/<name>`.
|
|
347
|
+
- Profile selection order: `OPENCODE_SCHEDULER_PROFILE` env var → file `active-profile`
|
|
348
|
+
in the base directory → `default`. Switching profiles writes the marker and requires
|
|
349
|
+
an OpenCode restart because plugin directories are resolved at module load time.
|
|
350
|
+
- Dashboard port per profile: `OPENCODE_SCHEDULER_PORT` env var → port from
|
|
351
|
+
`profile.json` → server default (3782, then 4782/5782 fallback).
|
|
352
|
+
- RPC: `get_profiles` lists profiles with dirs, ports and the active flag;
|
|
353
|
+
`set_profile` switches the active profile (restart hint); `create_profile` /
|
|
354
|
+
`delete_profile` manage named profiles (`default` cannot be deleted).
|
|
355
|
+
|
|
356
|
+
### Workspace environment variables (Sprint 21)
|
|
357
|
+
|
|
358
|
+
Each workspace can carry env variables that are injected into every task run in that
|
|
359
|
+
workspace:
|
|
360
|
+
|
|
361
|
+
- `env` — explicit `KEY=VALUE` pairs stored in SQLite as JSON;
|
|
362
|
+
- `envFile` — optional path to a `.env` file whose variables are loaded first, then
|
|
363
|
+
explicit pairs override them;
|
|
364
|
+
- File format: `KEY=value` lines, `#` comments, blank lines, leading `export `,
|
|
365
|
+
values in matching quotes are unquoted;
|
|
366
|
+
- Key validation: `^[A-Za-z_][A-Za-z0-9_]*$`, max 100 pairs per workspace;
|
|
367
|
+
- Delivery: at task create/update the plugin writes `<PLUGIN_DIR>/env/<sanitized>.env`
|
|
368
|
+
with real values (mode `0600` on POSIX) and passes it to the wrapper
|
|
369
|
+
(Windows: `-EnvFile "<path>"`; POSIX: `set -a; . "$ENV_FILE"; set +a` before the
|
|
370
|
+
`opencode run` invocation);
|
|
371
|
+
- Secret masking: keys matching `/(TOKEN|SECRET|PASS|PASSWORD|KEY|CREDENTIAL|AUTH)/i`
|
|
372
|
+
are shown as `***` in logs and masked API responses — values never leak into logs.
|
|
373
|
+
|
|
374
|
+
## Observability
|
|
375
|
+
|
|
376
|
+
### History
|
|
377
|
+
|
|
378
|
+
Every run becomes a row: status, start/finish, duration, error, tokens, cost, model,
|
|
379
|
+
pre/post-flight results, next chained task, workspace and tool restrictions. Statuses:
|
|
380
|
+
|
|
381
|
+
| Status | Meaning |
|
|
382
|
+
| --- | --- |
|
|
383
|
+
| `running` | started, not finished |
|
|
384
|
+
| `success` | finished, no Quality Gate failure |
|
|
385
|
+
| `error` | agent error, hook failure or Quality Gate failure |
|
|
386
|
+
| `timeout` | killed by the timeout |
|
|
387
|
+
| `partial` | matrix aggregate with both successes and failures |
|
|
388
|
+
|
|
389
|
+
### Metrics
|
|
390
|
+
|
|
391
|
+
Per-task counters and totals: runs, successes, errors, tokens, cost. Available through
|
|
392
|
+
`get_history`, the RPC layer and the dashboard header. A 14-day analytics slice —
|
|
393
|
+
Per-day buckets (UTC), success rate, token-based cost estimate, top tasks by cost,
|
|
394
|
+
matrix and model breakdowns — is available through `get_analytics` /
|
|
395
|
+
`GET /api/analytics` and the dashboard's **Analytics for the period** block.
|
|
396
|
+
pruned automatically (age and size limits, see Settings) and can be exported as
|
|
397
|
+
CSV/JSON (`GET /api/history/export`), or as OTLP/JSON for OpenTelemetry
|
|
398
|
+
(`GET /api/history/export?format=otlp`).
|
|
399
|
+
|
|
400
|
+
The same slice carries a **"Saved"** counter: runs that spent tokens without
|
|
401
|
+
a recorded cost (local models, prepaid plans) are priced against a reference cloud
|
|
402
|
+
rate of $0.01 / 1k tokens. The KPI is labelled as an estimate and links to
|
|
403
|
+
[docs/SAVINGS.md](SAVINGS.md) with the full methodology; `report.savings` exposes
|
|
404
|
+
`savedUsd`, `runs`, `tokens` and a per-task breakdown.
|
|
405
|
+
|
|
406
|
+
### Prometheus
|
|
407
|
+
|
|
408
|
+
`GET /metrics` exposes the Prometheus text format (0.0.4): `opencode_scheduler_info`,
|
|
409
|
+
`up`, `queue_depth`, `history_records`, `runs_total{task,status}`,
|
|
410
|
+
`errors_total{task}`, `tokens_total{task}`, `cost_usd_total{task}` and the
|
|
411
|
+
`run_duration_seconds` histogram (1 s … 3600 s + `+Inf`). `runs_total` has
|
|
412
|
+
separate `success`, `error` and `partial` statuses; `errors_total` counts only
|
|
413
|
+
errors and timeouts, so `partial` never inflates it. Values are read from
|
|
414
|
+
SQLite at scrape time, so no extra agent or exporter process is required.
|
|
415
|
+
|
|
416
|
+
### Structured logs
|
|
417
|
+
|
|
418
|
+
Every run start/finish and every webhook decision is appended to
|
|
419
|
+
`<PLUGIN_DIR>/logs/runs.jsonl` (one JSON object per line, 10 MiB rotation to
|
|
420
|
+
`runs.jsonl.1`). `GET /api/logs` returns newest-first records and supports `task`,
|
|
421
|
+
`status`, `event`, `since`, `until`, `limit` and `format=jsonl`. The database
|
|
422
|
+
`history` table remains the source of truth for aggregates; JSONL is for log
|
|
423
|
+
shipping and debugging and never blocks a run if writing fails.
|
|
424
|
+
|
|
425
|
+
### Incoming webhooks
|
|
426
|
+
|
|
427
|
+
`POST /api/hooks/:task?token=…` starts a task from GitHub Actions, GitLab CI or any
|
|
428
|
+
external system. The request must carry an HMAC-SHA256 of the raw body in
|
|
429
|
+
`X-Scheduler-Signature: sha256=<hex>` (GitHub's `X-Hub-Signature-256` and a bare
|
|
430
|
+
hex digest are also accepted). The token may instead come from `X-Scheduler-Token`
|
|
431
|
+
or `X-Gitlab-Token`. An optional `X-Scheduler-Timestamp` is checked against
|
|
432
|
+
`timestampToleranceSeconds`. Hooks are disabled by default; enabling them with empty
|
|
433
|
+
credentials generates a token and secret automatically. Errors: 401 (bad
|
|
434
|
+
token/signature/timestamp), 403 (channel disabled or credentials missing), 404
|
|
435
|
+
(unknown task), 413 (body over `maxBodyBytes`). The dashboard still binds to
|
|
436
|
+
localhost only, so external CI needs a tunnel or self-hosted runner.
|
|
437
|
+
|
|
438
|
+
#### Replay protection guidance for senders
|
|
439
|
+
|
|
440
|
+
Both remaining authentication modes are replayable at the transport level, so
|
|
441
|
+
senders should be chosen with that in mind:
|
|
442
|
+
|
|
443
|
+
- **Signature with `timestampToleranceSeconds = 0` (legacy).** The HMAC covers
|
|
444
|
+
only the body, so any intercepted request can be replayed verbatim, forever.
|
|
445
|
+
Set a non-zero tolerance and send `X-Scheduler-Timestamp` (unix seconds or
|
|
446
|
+
milliseconds): the signature then covers `<timestamp>.<body>` and a captured
|
|
447
|
+
request stops working outside the window.
|
|
448
|
+
- **Token-only mode.** A bearer token in a query parameter or header is also
|
|
449
|
+
replayable — the scheduler cannot distinguish a repeat from a replay. If you
|
|
450
|
+
cannot switch to timestamp-signed HMAC, mitigate instead: keep the token in
|
|
451
|
+
CI secrets (not in code), rotate it regularly, scope one token per task, and
|
|
452
|
+
make the target task idempotent so an accidental replay does no harm.
|
|
453
|
+
- **GitHub Actions.** GitHub does not send `X-Scheduler-Timestamp` itself, so
|
|
454
|
+
`X-Hub-Signature-256` alone runs in legacy (replayable) mode. Prefer a
|
|
455
|
+
workflow step that signs `<timestamp>.<body>` with the shared secret, or rely
|
|
456
|
+
on short-lived workflow runs and idempotent tasks.
|
|
457
|
+
- The scheduler itself performs no replay cache: unique-request deduplication
|
|
458
|
+
(e.g. event IDs) is the sender's responsibility.
|
|
459
|
+
|
|
460
|
+
### OpenTelemetry
|
|
461
|
+
|
|
462
|
+
History can be exported as OTLP/JSON: one span per run, deterministic 32-hex
|
|
463
|
+
`traceId` and 16-hex `spanId`, nanosecond timestamps, task/status/duration/tokens/
|
|
464
|
+
cost/model/error attributes and OK/ERROR status. The output can be posted to an
|
|
465
|
+
OpenTelemetry Collector or inspected directly.
|
|
466
|
+
|
|
467
|
+
### Logs
|
|
468
|
+
|
|
469
|
+
Each run appends to `logs/<task>.log` — pre/post hooks, Quality Gate output and the
|
|
470
|
+
agent's stdout/stderr. `get_task_logs` returns the tail (1–1000 lines).
|
|
471
|
+
|
|
472
|
+
### Dry run
|
|
473
|
+
|
|
474
|
+
`dry_run` simulates one task or every task: execution order, DAG prerequisites, matrix
|
|
475
|
+
fan-out and estimated time. Nothing is executed and nothing is created.
|
|
476
|
+
|
|
477
|
+
### Dashboard
|
|
478
|
+
|
|
479
|
+
A local web dashboard shows tasks, matrix tabs, per-workspace summaries, DAG markers,
|
|
480
|
+
metrics, a 14-day analytics block (KPIs, daily bar chart, top tasks by cost, matrices),
|
|
481
|
+
recent runs and CSV/JSON history export. It binds to localhost and has no authentication
|
|
482
|
+
— do not expose it. `GET /api/health` reports plugin version, scheduler backend, queue
|
|
483
|
+
depth and database status for external monitoring.
|
|
484
|
+
|
|
485
|
+
## Management
|
|
486
|
+
|
|
487
|
+
### Templates
|
|
488
|
+
|
|
489
|
+
Save a definition as a reusable template, then create tasks from it with one click or
|
|
490
|
+
one tool call.
|
|
491
|
+
|
|
492
|
+
### Export and import
|
|
493
|
+
|
|
494
|
+
`export_tasks` produces a versioned JSON document with definitions, including matrix
|
|
495
|
+
configuration and `matrixParentId`. `import_tasks` validates every record and reports
|
|
496
|
+
per-record errors instead of failing the whole batch. Unknown workspaces and invalid
|
|
497
|
+
matrix combinations are rejected explicitly.
|
|
498
|
+
|
|
499
|
+
### Notifications
|
|
500
|
+
|
|
501
|
+
Notifications on run completion through three independent channels — webhook, Telegram
|
|
502
|
+
and native OS notifications — configurable in settings and testable with
|
|
503
|
+
`test_notification`.
|
|
504
|
+
|
|
505
|
+
- **Webhook delivery:** per-task completion (success/error/timeout) through a
|
|
506
|
+
Discord/Slack compatible webhook (`{ content, text }`). `webhook.timeoutMs`
|
|
507
|
+
(default 10 000), `webhook.retryCount` (default 2) and `webhook.retryDelayMs`
|
|
508
|
+
(default 1000) control the request; network errors, timeouts, HTTP 5xx and 429 are
|
|
509
|
+
retried with exponential backoff (capped at 30 s), other 4xx are not.
|
|
510
|
+
- **Telegram:** Bot API `sendMessage` with `chat_id`, `parse_mode` (`HTML`,
|
|
511
|
+
`MarkdownV2`, `Markdown` or plain text), optional silent mode, forum topic
|
|
512
|
+
(`messageThreadId`) and a dashboard link (`includeDashboardLink`). Configured in the
|
|
513
|
+
GUI or with `manage_settings` → `notifications.telegram`. `botToken` and `chatId`
|
|
514
|
+
may instead come from `OPENCODE_SCHEDULER_TELEGRAM_BOT_TOKEN` and
|
|
515
|
+
`OPENCODE_SCHEDULER_TELEGRAM_CHAT_ID` so no secret is stored in `settings.json`;
|
|
516
|
+
the token is masked in every error message and log line.
|
|
517
|
+
- **Native OS notifications:** Windows Toast (PowerShell/WinRT), macOS Notification
|
|
518
|
+
Center (`osascript`) and Linux `notify-send`. No extra dependency: `node-notifier`
|
|
519
|
+
is not required. `notifications.native.sound` toggles the sound where supported.
|
|
520
|
+
- **Templates:** `templates.success` and `templates.error` accept placeholders
|
|
521
|
+
`{task}`, `{status}`, `{duration}`, `{error}`, `{emoji}`, `{cost}` and `{tokens}`.
|
|
522
|
+
When token/cost data is present the message gains a ` · 1500 tok · $0.0060` suffix.
|
|
523
|
+
- **Filters:** `filters.include` / `filters.exclude` are task-name patterns with `*`
|
|
524
|
+
wildcards; an empty include list means all tasks, exclude wins.
|
|
525
|
+
- **Quiet hours:** `quietHours.enabled` with `from`/`to` in `HH:MM` (an overnight
|
|
526
|
+
range such as 22:00 → 08:00 is supported). During the window `success` and
|
|
527
|
+
`partial` are suppressed while `error` and `timeout` are still delivered.
|
|
528
|
+
- **Dedup (31.2):** `notifications.dedup.enabled` groups identical task + status
|
|
529
|
+
notifications inside `windowMinutes` (default 60). With `suppressDuplicates`,
|
|
530
|
+
non-important repeats are suppressed; statuses listed in `importantStatuses`
|
|
531
|
+
(default `error`, `timeout`) are always delivered and get a localized repeat
|
|
532
|
+
suffix, e.g. `(repeat 3)`. Counters live in the SQLite `notification_dedup`
|
|
533
|
+
table, so they survive the short-lived `record-history` processes, and
|
|
534
|
+
`maxCount` caps the counter.
|
|
535
|
+
- **Matrix notifications:** on family completion — success, `partial` (`onPartial`)
|
|
536
|
+
and all clones failed (`onAllFailed`). A stuck detector reports clones running
|
|
537
|
+
longer than `matrix.stuckAfterMinutes` (default 60, `0` disables) once per run.
|
|
538
|
+
- **Digest:** `digest.enabled` sends a daily (`frequency: "daily"`, at `digest.time`)
|
|
539
|
+
or weekly (Mondays, catch-up afterwards) summary: runs, success rate, cost, tokens
|
|
540
|
+
and top errors through every enabled channel. Also available as the
|
|
541
|
+
`send_digest` RPC and the GUI's **Send digest now** button (manual sends
|
|
542
|
+
do not move the schedule).
|
|
543
|
+
- **Test button:** sends a test message to `all`, `webhook`, `telegram` or `native`
|
|
544
|
+
and reports per-channel success/failure. Failures in one channel never block the
|
|
545
|
+
others and never throw into the task run.
|
|
546
|
+
|
|
547
|
+
### Secrets (Sprint 26)
|
|
548
|
+
|
|
549
|
+
Encrypted secret storage in `<PLUGIN_DIR>/secrets.json` with AES-256-GCM and a
|
|
550
|
+
32-byte key file `secrets.key` (mode 0600 on POSIX; on Windows an ACL granting only
|
|
551
|
+
the current user, applied via `icacls`). The `manage_secrets` tool (and the **Secrets**
|
|
552
|
+
GUI panel) supports `list`, `set` and `delete`. Secret names match
|
|
553
|
+
`[A-Za-z0-9_.-]` and are up to 64 characters; list shows only name, masked preview
|
|
554
|
+
(`••••` + last 4 chars) and update time — never the value.
|
|
555
|
+
|
|
556
|
+
In task workspace `env`, reference a secret as `${secret:NAME}`. The value is
|
|
557
|
+
substituted at run time (missing secrets resolve to an empty string with a
|
|
558
|
+
name-only warning). Secret references survive masking — they are shown verbatim in
|
|
559
|
+
the GUI env editor — while literal secret-like values (`TOKEN=`, `PASSWORD=`, …)
|
|
560
|
+
are masked as `***` in logs, structured logs, history and audit.
|
|
561
|
+
|
|
562
|
+
#### Recovering a quarantined secrets store
|
|
563
|
+
|
|
564
|
+
If `secrets.json` fails to parse, it is quarantined, not deleted: the file is
|
|
565
|
+
renamed to `secrets.json.corrupt-<timestamp>` next to the original. This is a
|
|
566
|
+
side effect of a read operation — recovery is **manual by design** so that no
|
|
567
|
+
automatic rewrite can destroy data:
|
|
568
|
+
|
|
569
|
+
1. Find the quarantined file in the plugin directory: `secrets.json.corrupt-*`
|
|
570
|
+
(Windows: `%APPDATA%\opencode\windows-scheduler\`, macOS/Linux:
|
|
571
|
+
`~/.config/opencode/windows-scheduler/` or `$XDG_CONFIG_HOME`).
|
|
572
|
+
2. Inspect it: the corruption is usually truncated JSON (interrupted write) or
|
|
573
|
+
manual editing. Fix the JSON syntax in a text editor.
|
|
574
|
+
3. Copy the fixed file back to `secrets.json` (keep the `.corrupt-*` copy as a
|
|
575
|
+
backup) and verify with `manage_secrets` (`action: "list"`).
|
|
576
|
+
4. If the file cannot be repaired, secrets are re-set with `manage_secrets`
|
|
577
|
+
(`action: "set"`); values encrypted with a lost `secrets.key` cannot be
|
|
578
|
+
recovered — re-enter them.
|
|
579
|
+
5. In the rarer case where even the rename failed, writes stay blocked
|
|
580
|
+
(`corruptedStore` is set) until the `.corrupt-*` path is cleared manually —
|
|
581
|
+
move the broken file away yourself, then re-set the secrets.
|
|
582
|
+
|
|
583
|
+
### Audit log (Sprint 26)
|
|
584
|
+
|
|
585
|
+
Every mutation — task create/update/delete/run, settings, templates, profiles,
|
|
586
|
+
workspaces, secrets, import, history cleanup — is recorded in an `audit_log`
|
|
587
|
+
table in SQLite with action, target type/target, actor (`mcp`/`gui`/`http`),
|
|
588
|
+
source, redacted details and remote address. Indexes on `ts` and `action`;
|
|
589
|
+
retention defaults to 90 days / 10 000 records with automatic cleanup.
|
|
590
|
+
|
|
591
|
+
The `get_audit_log` tool (and the **Audit log** GUI panel) reads the journal
|
|
592
|
+
with filters by `action`, `target`, `actor`, `since`/`until` and `limit`. Also
|
|
593
|
+
available as RPC `get_audit` and HTTP `GET /api/audit`. Secret values in details
|
|
594
|
+
are redacted; `${secret:NAME}` references are preserved verbatim.
|
|
595
|
+
|
|
596
|
+
### Crash recovery
|
|
597
|
+
|
|
598
|
+
Runs left in `running` after a crash are marked `error` on the next plugin start, so
|
|
599
|
+
the timeline never lies. Orphaned matrix clones are cleaned up at startup as well.
|
|
600
|
+
|
|
601
|
+
### Settings
|
|
602
|
+
|
|
603
|
+
Global defaults (timeout, concurrency, notifications, history retention) live in
|
|
604
|
+
`settings.json` and are editable from the GUI/RPC layer. History retention keeps the
|
|
605
|
+
raw run log bounded: `history.retentionDays` (default 30) and `history.maxRecords`
|
|
606
|
+
(default 5000); `0` disables the respective limit. Cleanup runs at most once a day on
|
|
607
|
+
plugin start, records `lastCleanupAt` / `lastCleanupDeleted`, and is also available as
|
|
608
|
+
the `cleanup_history` RPC and the GUI's **Clear now** button. Aggregates in
|
|
609
|
+
`metrics.json` are not affected by retention.
|
|
610
|
+
|
|
611
|
+
## Agent interface
|
|
612
|
+
|
|
613
|
+
Twenty-five tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
|
|
614
|
+
`run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
|
|
615
|
+
`manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
|
|
616
|
+
`get_analytics`, `manage_settings`, `manage_local_ai`, `manage_templates`, `manage_profiles`,
|
|
617
|
+
`transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
|
|
618
|
+
`manage_secrets`, `get_audit_log`,
|
|
619
|
+
`emit_event`.
|
|
620
|
+
|
|
621
|
+
A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
|
|
622
|
+
least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
|
|
623
|
+
create → dry-run → run-now → inspect loop. It is registered automatically by the
|
|
624
|
+
plugin, no installation step required.
|
|
625
|
+
|
|
626
|
+
The `manage_local_ai` tool reads, updates and tests the local triage settings
|
|
627
|
+
(`action: "get" | "update" | "test"`); see [LOCAL-AI.md](LOCAL-AI.md).
|
|
628
|
+
|
|
629
|
+
## Local assistant (triage)
|
|
630
|
+
|
|
631
|
+
An optional offline model classifies failed and partial runs (category, severity,
|
|
632
|
+
confidence, reason). The model never suppresses a notification by itself: only a
|
|
633
|
+
matching rules-engine rule with `action: "skip"` can do that. It is opt-in and
|
|
634
|
+
fail-open: without a model the rules engine or direct delivery takes over, and
|
|
635
|
+
notifications are never blocked by an unavailable model.
|
|
636
|
+
It never changes run status, retries, Quality Gates, DAG dependencies or history.
|
|
637
|
+
|
|
638
|
+
- `mode`: `off` (default), `rules`, `llm` or `auto` (model, then rules).
|
|
639
|
+
- `fallback`: `rules` (default) or `notify` when the model fails or is unsure.
|
|
640
|
+
The legacy value `skip` is accepted as an alias for `notify`.
|
|
641
|
+
- `confidenceThreshold`: minimum model confidence (0..1).
|
|
642
|
+
- `rules` omitted means the built-in rules; `rules: []` disables them; a custom
|
|
643
|
+
array replaces the built-in set.
|
|
644
|
+
- Built-in rules cover errors, status, cost and task name
|
|
645
|
+
(deploy/release/backup/migration); all are notify-only. Examples are in
|
|
646
|
+
[LOCAL-AI.md](LOCAL-AI.md).
|
|
647
|
+
- The GUI shows a colored connection status (not checked / checking /
|
|
648
|
+
connected / no connection) and resets it when the mode, URL or model changes.
|
|
649
|
+
- In `llm`/`auto`, triage is asynchronous: the notification is delivered
|
|
650
|
+
immediately and a detached worker writes the verdict to the audit. Only
|
|
651
|
+
`rules` mode triages before delivery, because only rules can suppress.
|
|
652
|
+
- `notifications.embedding` adds semantic dedup on top of the exact dedup:
|
|
653
|
+
messages are converted to normalized bag-of-words vectors stored in SQLite,
|
|
654
|
+
compared by cosine similarity against the window, and suppressed above
|
|
655
|
+
`threshold` (0.85 default). Important statuses are never suppressed. No new
|
|
656
|
+
dependencies and no external embedding model are required.
|
|
657
|
+
- `notifications.summary` renders at most three short lines for Telegram and
|
|
658
|
+
toasts. The model returns strict JSON `{"lines": [...]}`; any failure falls
|
|
659
|
+
back to deterministic truncation (status, error, runtime/tokens/cost), and
|
|
660
|
+
delivery waits at most `summary.timeoutMs` (8 s default).
|
|
661
|
+
- Shadow mode logs decisions to the persistent audit journal
|
|
662
|
+
(`get_audit_log`, action `triage.decision`) without suppressing notifications,
|
|
663
|
+
so triage can be evaluated safely before it is enforced and the report
|
|
664
|
+
survives restarts.
|
|
665
|
+
|
|
666
|
+
Setup, model tiers by RAM, the `npm run bench:local` benchmark, shadow workflow
|
|
667
|
+
and troubleshooting (including `OLLAMA_CONTEXT_LENGTH`) are documented in
|
|
668
|
+
[LOCAL-AI.md](LOCAL-AI.md).
|
|
669
|
+
|
|
670
|
+
## Platform support
|
|
671
|
+
|
|
672
|
+
| Capability | Windows | Linux | macOS |
|
|
673
|
+
| --- | --- | --- | --- |
|
|
674
|
+
| Cron scheduling | Task Scheduler | crontab | launchd |
|
|
675
|
+
| Fallback | — | — | crontab |
|
|
676
|
+
| Timeout and lock | PowerShell wrapper | bash wrapper | bash wrapper |
|
|
677
|
+
| File triggers | chokidar | chokidar | chokidar |
|
|
678
|
+
| History, metrics, dashboard | yes | yes | yes |
|
|
679
|
+
| Agent tools and skill | yes | yes | yes |
|
|
680
|
+
| Runs without a logged-on user | opt-in (`runWhenLoggedOff`) | always (crontab) | no (per-user agent) |
|
|
681
|
+
|
|
682
|
+
## Limits and non-goals
|
|
683
|
+
|
|
684
|
+
- **No one-shot scheduling without `triggerType: "once"`.** One-shot runs exist
|
|
685
|
+
via `runAt`/`delaySeconds`; use `run_task_now` for immediate runs.
|
|
686
|
+
- **No session continuity beyond the built-in `session` modes.** `new`, `reuse`
|
|
687
|
+
and `last` cover the common cases; per-message session forking/branching is
|
|
688
|
+
not supported.
|
|
689
|
+
- **No sandbox.** Hooks, Quality Gates and prompts run with your user privileges.
|
|
690
|
+
- **No authentication on the dashboard.** Localhost only by design.
|
|
691
|
+
- **Secrets are not encrypted.** Use environment variables or an external secret
|
|
692
|
+
manager.
|
|
693
|
+
- **`allowedTools` / `deniedTools` restrict the agent process, not the whole job.**
|
|
694
|
+
Hooks, Quality Gates and wrapper scripts still run with your user privileges, and a
|
|
695
|
+
project-level or system `opencode.jsonc` can weaken task-scoped denies. See the
|
|
696
|
+
permission-enforcement limitations in ARCHITECTURE.md.
|
|
697
|
+
- **Matrix clones are separate tasks.** They appear in the task list (grouped under the
|
|
698
|
+
parent) and consume global concurrency slots like any other run.
|