agent-steward 0.0.1 → 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/README.md +306 -15
- 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 +133 -13
- 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
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Cross-platform: Windows → macOS → Linux
|
|
2
|
+
|
|
3
|
+
The plugin is no longer tied to `schtasks`. The scheduler is an abstract layer with
|
|
4
|
+
three implementations, and run wrappers are generated for the target OS.
|
|
5
|
+
|
|
6
|
+
Translations: [Русский](docs/CROSS_PLATFORM.ru.md) · [中文](docs/CROSS_PLATFORM.zh.md)
|
|
7
|
+
|
|
8
|
+
## Architecture
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
src/
|
|
12
|
+
index.ts # tools, RPC, plugin lifecycle
|
|
13
|
+
gui.tsx # GUI panel (title comes from RPC)
|
|
14
|
+
server.ts # web dashboard (dynamic title)
|
|
15
|
+
core/
|
|
16
|
+
scheduler/
|
|
17
|
+
types.ts # SchedulerBackend, CreateTaskOptions, RunTaskResult
|
|
18
|
+
index.ts # factory createSchedulerBackend() + getSchedulerTitle()
|
|
19
|
+
windows.ts # WindowsScheduler (schtasks)
|
|
20
|
+
linux.ts # LinuxScheduler (crontab)
|
|
21
|
+
mac.ts # MacScheduler (launchd / LaunchAgents)
|
|
22
|
+
posix.ts # shared base for Linux/macOS (task registry)
|
|
23
|
+
registry.ts # persistent task registry for POSIX backends
|
|
24
|
+
logs.ts # cross-platform task log reader
|
|
25
|
+
wrappers/
|
|
26
|
+
bash.ts # .sh wrapper generator for Linux/macOS
|
|
27
|
+
ps-wrapper.ts # .ps1/.cmd wrappers for Windows (unchanged)
|
|
28
|
+
record-history.ts # metrics/history + retry/chains (via backend)
|
|
29
|
+
cron-to-schtasks.ts # cron → schtasks (Windows only)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Interface
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
interface SchedulerBackend {
|
|
36
|
+
readonly platform: NodeJS.Platform;
|
|
37
|
+
readonly title: string; // "Windows Task Scheduler" / "OpenCode Scheduler"
|
|
38
|
+
createTask(options: CreateTaskOptions): Promise<void>;
|
|
39
|
+
deleteTask(name: string): Promise<void>;
|
|
40
|
+
runTask(name: string): Promise<RunTaskResult>;
|
|
41
|
+
listTasks(): Promise<ScheduledTaskInfo[]>;
|
|
42
|
+
pauseTask(name: string): Promise<void>;
|
|
43
|
+
resumeTask(name: string): Promise<void>;
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The factory picks an implementation from `process.platform`:
|
|
48
|
+
`win32 → WindowsScheduler`, `darwin → MacScheduler`, everything else → `LinuxScheduler`.
|
|
49
|
+
|
|
50
|
+
## How each OS works
|
|
51
|
+
|
|
52
|
+
### Windows (behaviour unchanged)
|
|
53
|
+
- Tasks are registered in Windows Task Scheduler via `schtasks` under `\OpenCode\windows-scheduler\`.
|
|
54
|
+
- Wrapper: `run-task.ps1` plus a per-task `run-<name>.cmd` in `%APPDATA%\opencode\windows-scheduler\wrapper`.
|
|
55
|
+
- Logs: `%APPDATA%\opencode\windows-scheduler\logs\<name>.log`.
|
|
56
|
+
- cron is converted to schtasks (`convertCronToSchTasks`) — the same pattern set as before.
|
|
57
|
+
|
|
58
|
+
### Linux
|
|
59
|
+
- Tasks live in a managed `crontab` block:
|
|
60
|
+
```
|
|
61
|
+
# >>> opencode-scheduler >>>
|
|
62
|
+
# task: my-task
|
|
63
|
+
*/5 * * * * /bin/bash '/…/wrapper/run-my-task.sh' >> '/…/logs/my-task.log' 2>&1
|
|
64
|
+
# <<< opencode-scheduler <<<
|
|
65
|
+
```
|
|
66
|
+
- Pause = a line prefixed with `# PAUSED: ` (the block is rebuilt from the registry).
|
|
67
|
+
- Tasks with a `file` trigger never reach crontab — the plugin's FileWatchManager starts them.
|
|
68
|
+
- Wrapper: `~/.config/opencode/windows-scheduler/wrapper/run-<name>.sh` (chmod 0755).
|
|
69
|
+
- Full cron syntax (unlike Windows), because crontab understands it natively.
|
|
70
|
+
- Delete/rebuild touches only its own block; other `crontab` lines are left alone.
|
|
71
|
+
|
|
72
|
+
### macOS
|
|
73
|
+
- Tasks are LaunchAgent plists at `~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`.
|
|
74
|
+
- Schedule: `StartInterval` for `* * * * *` and `*/N`, `StartCalendarInterval` for `M * * * *`,
|
|
75
|
+
`M H * * *`, `M H * * D`.
|
|
76
|
+
- Pause = `launchctl unload -w`, resume = `launchctl load -w`.
|
|
77
|
+
- Wrapper is the same `.sh` as on Linux; config paths:
|
|
78
|
+
`~/.config/opencode/windows-scheduler/` (or `$XDG_CONFIG_HOME`).
|
|
79
|
+
|
|
80
|
+
### Shared POSIX wrapper (`.sh`)
|
|
81
|
+
- `cd` into the working directory, `opencode run` with the prompt read from a file.
|
|
82
|
+
- Logs are appended with `>>` and prefixed with timestamps.
|
|
83
|
+
- Locking via atomic `mkdir` — protects against parallel runs.
|
|
84
|
+
- Timeout: child process + watchdog (`TERM`, then `KILL`).
|
|
85
|
+
- Quality Gate: `bash -lc "<command>"` (the `cmd.exe /c` equivalent on Windows).
|
|
86
|
+
- Metrics: `node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"` —
|
|
87
|
+
the same contract as the PowerShell wrapper, so history/metrics/retry/chains work everywhere.
|
|
88
|
+
- `PATH` is extended with `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, `~/.bun/bin`.
|
|
89
|
+
|
|
90
|
+
## Feature matrix
|
|
91
|
+
|
|
92
|
+
| Capability | Windows | Linux | macOS |
|
|
93
|
+
|---|---|---|---|
|
|
94
|
+
| Scheduler backend | `schtasks` | `crontab` | `launchd` LaunchAgents |
|
|
95
|
+
| Native cron subset | `* * * * *`, `*/N * * * *` (N ≤ 1439, 60 % N = 0), `M * * * *`, `M H * * *`, `M H * * D` | full cron | same subset as Windows |
|
|
96
|
+
| Other cron expressions | minute-poll + schedule gate | native cron | minute-poll + schedule gate |
|
|
97
|
+
| `*/N` in day-of-month / day-of-week | not native → poll | native | not native → poll |
|
|
98
|
+
| Pause / resume | `schtasks /change /disable` / `/enable` | `# PAUSED:` line in the managed block | `launchctl unload -w` / `load -w` |
|
|
99
|
+
| File triggers | in-process `FileWatchManager` | same | same |
|
|
100
|
+
| Task wrappers | `.cmd` + `.ps1` | `.sh` | `.sh` |
|
|
101
|
+
| Logs | `%APPDATA%\opencode\windows-scheduler\logs` | `~/.config/opencode/windows-scheduler/logs` | same as Linux |
|
|
102
|
+
| `secrets.key` protection | `icacls` (owner only) + `chmod` fallback | `chmod 0600` | `chmod 0600` |
|
|
103
|
+
| Dashboard | `127.0.0.1`, dynamic title | same | same |
|
|
104
|
+
| DAG / matrix / quality gates / notifications | in-plugin, OS-independent | same | same |
|
|
105
|
+
|
|
106
|
+
### Compromises
|
|
107
|
+
|
|
108
|
+
1. **Minute-poll.** Cron expressions outside the native subset, and tasks with a non-system
|
|
109
|
+
IANA time zone, are started every minute by the OS scheduler; `schedule-gate` decides
|
|
110
|
+
whether the run proceeds. The cost is one short-lived wrapper process per task per minute.
|
|
111
|
+
2. **`M H */N * *` is deliberately not converted to `schtasks /sc DAILY /mo N`.**
|
|
112
|
+
Cron counts days from the 1st of each month and resets at month boundaries; `/mo N`
|
|
113
|
+
counts days from the task creation date and does not reset. The two schedules are not
|
|
114
|
+
equivalent, so the expression stays in poll mode. A native variant would require
|
|
115
|
+
`MONTHLY` with an explicit `/d` list, not `DAILY /mo N`.
|
|
116
|
+
3. **DST.** The gate works with local wall-clock time. A nonexistent time (spring forward)
|
|
117
|
+
is skipped; an ambiguous time (fall back) runs at the first occurrence.
|
|
118
|
+
4. **`*/N * * * *` on Windows** is native only when `60 % N = 0` and `N ≤ 1439`.
|
|
119
|
+
Otherwise the task falls back to poll mode, because `schtasks /mo N` counts from the
|
|
120
|
+
creation moment while cron counts from the start of the hour.
|
|
121
|
+
5. **POSIX wrappers, crontab and launchd have not been executed on real Linux/macOS hosts**
|
|
122
|
+
(see Limitations); syntax and escaping are covered by tests only.
|
|
123
|
+
|
|
124
|
+
## GUI and dashboard
|
|
125
|
+
- The title is dynamic: "Windows Task Scheduler" on Windows, "OpenCode Scheduler" on macOS/Linux.
|
|
126
|
+
- The title comes from the `get_platform` RPC method → `{ platform, title }`.
|
|
127
|
+
- The title is used in the GUI panel, in the error fallback panel, and in the dashboard `<title>/<h1>`.
|
|
128
|
+
- Buttons, statuses, tables, DAG and metrics do not depend on the OS.
|
|
129
|
+
- Tool descriptions (`schedule_task` and others) substitute the actual scheduler name.
|
|
130
|
+
|
|
131
|
+
## Build and checks
|
|
132
|
+
- `npm run build` — OK, no errors.
|
|
133
|
+
- `npm run build:gui` — OK (`gui-experimental.cjs`, ~47.7 kB).
|
|
134
|
+
- Verified at runtime:
|
|
135
|
+
- titles for win32/darwin/linux;
|
|
136
|
+
- `cronToLaunchdSchedule` on several expressions;
|
|
137
|
+
- live `listTasks()` on Windows — tasks come back with short names (no prefix);
|
|
138
|
+
- `shellQuote` escaping (quotes, spaces, Cyrillic);
|
|
139
|
+
- `dist/index.js` imports fine, `dist` does not pull `schtasks.js` directly.
|
|
140
|
+
|
|
141
|
+
## Limitations and what to verify on real machines
|
|
142
|
+
1. `.sh` wrappers and crontab/launchd were **never executed** — the current Windows box has no
|
|
143
|
+
`bash`/WSL. Syntax and escaping were checked by hand; a run on Linux and macOS is still needed.
|
|
144
|
+
2. cron → launchd supports the same limited pattern set as Windows
|
|
145
|
+
(`* * * * *`, `*/N * * * *`, `M * * * *`, `M H * * *`, `M H * * D`).
|
|
146
|
+
Linux gets full cron.
|
|
147
|
+
3. The Windows task prefix (`\OpenCode\windows-scheduler\`) and the plugin id are kept for backwards compatibility.
|
|
148
|
+
4. `src/schtasks.ts` remains as a thin shim for old scripts (`test-create.cjs`, `test-run.cjs`);
|
|
149
|
+
all logic now lives in `core/scheduler/windows.ts`.
|
package/README.md
CHANGED
|
@@ -1,24 +1,315 @@
|
|
|
1
|
-
# agent-steward
|
|
1
|
+
# agent-steward
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> OpenCode V1 (≥ 1.18.29) and V2 plugin for scheduling and orchestrating AI agent jobs — cron, one-shot runs, DAG pipelines, matrix builds, quality gates, SQLite history and a local web dashboard. Runs on Windows, macOS and Linux. Free and open source (MIT).
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
[
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
5
|
+
[](https://github.com/DeadSno/agent-steward/actions/workflows/ci.yml)
|
|
6
|
+
[](https://www.npmjs.com/package/agent-steward)
|
|
7
|
+
[](https://www.npmjs.com/package/agent-steward)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](package.json)
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Translations: [Russian](docs/README.ru.md) · [中文](docs/README.zh.md).
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Quickstart
|
|
16
|
+
|
|
17
|
+
1. Install the plugin (see [Install](#install)) and restart OpenCode.
|
|
18
|
+
2. Ask the agent to schedule your first job — one call is enough:
|
|
19
|
+
|
|
20
|
+
> Schedule a task "morning-report" that runs every day at 09:00 with the prompt: "Summarize yesterday's git commits and write the report to ~/reports/".
|
|
21
|
+
|
|
22
|
+
3. Open the dashboard to watch it run: the agent prints the URL when the task is created (default `http://localhost:4380`), or ask for it later with the `get_dashboard_info` tool. Prefer a preview without installing anything? `node scripts/demo-dashboard.mjs` starts a demo dashboard at `http://localhost:4380`.
|
|
23
|
+
|
|
24
|
+
## Why
|
|
25
|
+
|
|
26
|
+
Most schedulers for AI agents are cron wrappers: they run a prompt on a timer and write a log file. This plugin treats agent jobs as **workflows**:
|
|
27
|
+
|
|
28
|
+
- **DAG pipelines** — a job waits for its dependencies, chains on success/error.
|
|
29
|
+
- **Matrix builds** — one template, N repositories, parallel or sequential, with concurrency limits and per-workspace overrides.
|
|
30
|
+
- **Quality gates** — a job is marked successful only if `npm test` (or any command) passes.
|
|
31
|
+
- **Observability** — SQLite history, metrics, logs, and a local web dashboard.
|
|
32
|
+
- **Runs without OpenCode open** - cron and one-shot jobs are registered with the native OS scheduler (Windows Task Scheduler, launchd, crontab) and survive reboots. File, git and MCP-event triggers are watched inside the plugin process, so they need OpenCode running.
|
|
33
|
+
|
|
34
|
+
Everything runs on your machine. No SaaS, no telemetry, no accounts.
|
|
35
|
+
|
|
36
|
+

|
|
37
|
+
|
|
38
|
+
Want to see it without installing OpenCode? `node scripts/demo-dashboard.mjs` starts the dashboard with demo data at http://localhost:4380.
|
|
39
|
+
|
|
40
|
+
## Features
|
|
41
|
+
|
|
42
|
+
| Area | What you get |
|
|
43
|
+
|---|---|
|
|
44
|
+
| Scheduling | cron expressions, one-shot runs via `runAt` / `delaySeconds`, native OS scheduler (Windows / macOS / Linux), IANA timezones (native where possible, minute-poll + gate otherwise), pause/resume, session continuity (`new` / `reuse` / `last` with `sessionMaxRuns` cleanup) |
|
|
45
|
+
| Reliability | lock-file no-overlap protection, timeouts with hard kill, retries with delay, crash recovery |
|
|
46
|
+
| Quality | Quality Gate command, before/after hooks, per-task allowed/denied tool lists |
|
|
47
|
+
| Orchestration | `dependsOn` DAG, `nextTaskOnSuccess` / `nextTaskOnError` chains, matrix fan-out (parallel/sequential, `continue`/`stop`, concurrency, per-workspace overrides, aggregator task) |
|
|
48
|
+
| Triggers | cron, one-shot (`triggerType: "once"`), git commits (`triggerType: "git"`, branch/path/ignore filters), file change (chokidar, with glob masks `watchGlobs`/`watchIgnore`), MCP events, incoming webhooks (`POST /api/hooks/:task` with HMAC) |
|
|
49
|
+
| Multi-repo | workspaces with path validation, per-workspace runs, matrix over one parent task |
|
|
50
|
+
| Observability | SQLite history (success / error / timeout / partial / running), metrics (duration, tokens, cost), JSONL run logs with `/api/logs`, Prometheus `/metrics`, OTLP export, per-task logs, local web dashboard with 14-day analytics, history retention and CSV/JSON export |
|
|
51
|
+
| Operations | dry-run preview, export/import JSON, templates, multi-channel notifications (webhook, Telegram, native OS toasts), quiet hours, digest, encrypted secrets (`${secret:NAME}`), audit log, settings |
|
|
52
|
+
| Interfaces | OpenCode GUI panel, web dashboard, 25 agent tools, built-in agent skill |
|
|
53
|
+
|
|
54
|
+
### Language
|
|
55
|
+
|
|
56
|
+
The interface ships in Russian (default), English and Simplified Chinese. The language
|
|
57
|
+
selector sits in the scheduler panel header (🌐 Auto / Русский / English / 中文) and is
|
|
58
|
+
also available through the `manage_settings` tool (`action: "update"`, `locale: "zh"`).
|
|
59
|
+
`locale: "auto"` (the "Auto" option) follows the OpenCode interface language: the panel
|
|
60
|
+
reacts to language changes immediately, and the resolved locale is sent to the server so
|
|
61
|
+
notifications, digests and the dashboard use the same language. The switch applies
|
|
62
|
+
without a restart. Dashboard localization is still being rolled out: some client-side
|
|
63
|
+
strings remain Russian for now. Agent tool descriptions and schemas stay English by
|
|
64
|
+
design, and diagnostics printed to the console stay Russian.
|
|
65
|
+
|
|
66
|
+
Catalogs live in `locales/ru.json`, `locales/en.json` and `locales/zh.json`; every key
|
|
67
|
+
must exist in all three, otherwise CI fails.
|
|
68
|
+
|
|
69
|
+
Documentation is separate from the interface locale: the English docs are the primary
|
|
70
|
+
source, with Russian (`docs/README.ru.md`) and Simplified Chinese (`docs/README.zh.md`,
|
|
71
|
+
`docs/FEATURES.zh.md`, `docs/FAQ.zh.md`, `docs/SAVINGS.zh.md`,
|
|
72
|
+
`docs/CROSS_PLATFORM.zh.md`) translations. Translations may lag behind the English
|
|
73
|
+
originals.
|
|
74
|
+
|
|
75
|
+
## Install
|
|
76
|
+
|
|
77
|
+
Requires OpenCode V1 ≥ 1.18.29 or V2, and Node.js 22.22+ (node:sqlite and chokidar 6 require Node.js 22.22+). See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for version support and the V1/V2 surface (GUI and RPC are V2-only; TUI works on both).
|
|
78
|
+
|
|
79
|
+
The config key differs between lines:
|
|
80
|
+
|
|
81
|
+
| OpenCode line | Key in `opencode.jsonc` |
|
|
82
|
+
|---|---|
|
|
83
|
+
| V1 (`1.18.29`–`1.19.x`) | `"plugin": ["opencode-windows-scheduler"]` |
|
|
84
|
+
| V2 (`≥ 2.2.7`) | `"plugins": ["opencode-windows-scheduler"]` |
|
|
85
|
+
|
|
86
|
+
Use the key of your line; there is no need to add both. On V2 the CLI does it for you:
|
|
12
87
|
|
|
13
88
|
```bash
|
|
14
|
-
|
|
89
|
+
opencode plugin add opencode-windows-scheduler
|
|
15
90
|
```
|
|
16
91
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
92
|
+
V1 — manual config:
|
|
93
|
+
|
|
94
|
+
```jsonc
|
|
95
|
+
{
|
|
96
|
+
"$schema": "https://opencode.ai/config.json",
|
|
97
|
+
"plugin": ["opencode-windows-scheduler"]
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
V2 — equivalent manual config:
|
|
102
|
+
|
|
103
|
+
```jsonc
|
|
104
|
+
{
|
|
105
|
+
"$schema": "https://opencode.ai/config.json",
|
|
106
|
+
"plugins": ["opencode-windows-scheduler"],
|
|
107
|
+
"experimental": {
|
|
108
|
+
"schedules": false
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`experimental.schedules: false` disables the built-in OpenCode scheduler so the agent does not confuse built-in job tools with this plugin's tools. Restart OpenCode after changing the config. The TUI panel is part of the same package (`exports["./tui"]`), so it is enabled by the same entry on both lines.
|
|
114
|
+
|
|
115
|
+
From source:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
git clone https://github.com/DeadSno/agent-steward.git
|
|
119
|
+
cd agent-steward
|
|
120
|
+
npm install
|
|
121
|
+
npm run build && npm run build:gui
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Agent tools
|
|
125
|
+
|
|
126
|
+
The agent gets the full feature set — 26 tools covering scheduling, pipelines, operations, observability and administration:
|
|
127
|
+
|
|
128
|
+
| Tool | Arguments | What it does |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| `schedule_task` | `name`, `prompt`, `schedule` for cron or `runAt` / `delaySeconds` for one-shot, optional `session` / `sessionMaxRuns`, `timeoutSeconds`, `model`, `priority`, `beforeScript`, `afterScript`, `qualityGate`, `dependsOn`, `retryCount`, `retryDelay`, `nextTaskOnSuccess`, `nextTaskOnError`, `triggerType` (`cron`/`file`/`git`/`mcp-event`/`once`), `mcpEvent`, `watchPath`, `watchGlobs`, `watchIgnore`, `gitBranch`, `gitPaths`, `gitIgnore`, `gitPollSeconds`, `activeDays`, `windowPolicy` (`skip`/`postpone`/`run`), `workingDirectory`, `workspaceId`, `allowedTools`, `deniedTools`, `legacyShell`, `matrix` | Registers a job with the OS scheduler (cron, one-shot, file, git or MCP-event trigger) |
|
|
131
|
+
| `list_tasks` | — | Returns jobs with schedule, status, next run, chains, workspace and matrix summary |
|
|
132
|
+
| `update_task` | `name` + any field to change | Partial update; omitted fields keep their values, empty values clear them, `matrix: null` removes the matrix |
|
|
133
|
+
| `delete_task` | `name` | Deletes a job (a matrix parent deletes clones and aggregator) |
|
|
134
|
+
| `run_task_now` | `name` | Runs a job immediately (matrix parent starts the fan-out) |
|
|
135
|
+
| `pause_task` | `name` | Pauses a job (matrix parent pauses every clone) |
|
|
136
|
+
| `resume_task` | `name` | Resumes a paused job |
|
|
137
|
+
| `get_history` | `taskName?`, `status?`, `limit?` | Recent runs with duration, tokens, cost, model, quality gate and hooks |
|
|
138
|
+
| `get_task_logs` | `name`, `lines?` | Tail of the run log |
|
|
139
|
+
| `dry_run` | `name?` | Simulates a pipeline (or every task): order, DAG, matrix fan-out, estimates |
|
|
140
|
+
| `manage_workspaces` | `action`, `id?`, `name?`, `path?`, `color?` | Multi-repo workspaces: list, add, update, delete |
|
|
141
|
+
| `matrix_control` | `action`, `name?` | Matrix results, cancel pending clones, clean up orphans, preview clones |
|
|
142
|
+
| `get_metrics` | — | Aggregate runs, successes and failures |
|
|
143
|
+
| `get_analytics` | `days?`, `topLimit?` | Period report: counts, success rate, duration, tokens, cost, top tasks |
|
|
144
|
+
| `manage_settings` | `action`, `maxConcurrent?`, `winterMode?`, `notifications?`, `history?` | Read/update global settings (concurrency, notifications, retention) |
|
|
145
|
+
| `manage_local_ai` | `action` (`get`/`update`/`test`), `mode?`, `baseUrl?`, `model?`, `timeoutMs?`, `fallback?`, `confidenceThreshold?`, `shadow?` | Read, update or test the local triage assistant; `test` sends one synthetic notification and reports latency and verdict |
|
|
146
|
+
| `manage_templates` | `action`, template fields | List, save or delete reusable task templates |
|
|
147
|
+
| `manage_profiles` | `action`, `name?`, `port?` | List, create, switch or delete isolated profiles |
|
|
148
|
+
| `transfer_tasks` | `action`, `data?` | Export all tasks to JSON or import them back |
|
|
149
|
+
| `send_notification` | `action` (`test`/`digest`), `channel?` (`all`/`webhook`/`telegram`/`native`) | Test the notification channels or send the digest |
|
|
150
|
+
| `get_dashboard_info` | — | Dashboard port/URL, platform, title, active profile |
|
|
151
|
+
| `cleanup_history` | `retentionDays?`, `maxRecords?` | Delete old history by age and/or record cap |
|
|
152
|
+
| `manage_secrets` | `action`, `name?`, `value?` | Create, list or delete AES-256-GCM encrypted secrets used in task `env` |
|
|
153
|
+
| `get_audit_log` | `action?`, `target?`, `actor?`, `since?`, `until?`, `limit?` | Mutation audit journal: who changed what, when and via which interface |
|
|
154
|
+
| `emit_event` | `eventName`, `payload?` | Start tasks subscribed to an MCP event |
|
|
155
|
+
|
|
156
|
+
`schedule_task` also accepts the full matrix configuration (`workspaceIds`, `strategy`, `failureMode`, `aggregation`, `concurrency`, `overrides`, `createAggregator`).
|
|
157
|
+
|
|
158
|
+
## Permissions
|
|
159
|
+
|
|
160
|
+
Agent jobs run with `opencode run --auto`, so their tool policy must be explicit. The global `permissions.defaultPolicy` setting (GUI → Settings, or `manage_settings`) chooses the baseline:
|
|
161
|
+
|
|
162
|
+
| Policy | Allowed by default | Denied by default |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| `hybrid` (default) | read, edit, glob, grep, subagent, skill, webfetch, websearch | shell, question |
|
|
165
|
+
| `secure` | read, glob, grep, skill | edit, shell, question, webfetch, websearch, subagent |
|
|
166
|
+
| `legacy` | all ten actions | — |
|
|
167
|
+
|
|
168
|
+
`deniedTools` always wins. A non-empty `allowedTools` is an allowlist: it denies every action that is not listed, and can explicitly re-enable an action denied by the policy (for example `shell`). `legacyShell: true` re-enables `shell` only under `hybrid`, for tasks migrated from older versions.
|
|
169
|
+
|
|
170
|
+
Blocked actions are written to the audit journal as `tool.blocked` with `reason: "default-policy"` and a `hint`, and each run logs the active policy.
|
|
171
|
+
|
|
172
|
+
Recommended pattern: keep `git commit`/`push`, builds and tests outside the agent, in `qualityGate` or `afterScript` (the wrapper runs them with `bash -c`), and leave the agent with `read`/`edit`. Most jobs then need no `shell` at all.
|
|
173
|
+
|
|
174
|
+
## Agent skill
|
|
175
|
+
|
|
176
|
+
The plugin registers a built-in skill, `scheduled-job-best-practices`, so the agent loads guidance only when it is relevant: cron design, self-contained prompts, Quality Gates, matrix concurrency, DAG rules and post-incident diagnosis. No manual `.opencode/skills` setup is needed. The skill ships with `references/recipes.md` — eight copy-ready configurations.
|
|
177
|
+
|
|
178
|
+
## Matrix builds
|
|
179
|
+
|
|
180
|
+
```jsonc
|
|
181
|
+
{
|
|
182
|
+
"name": "deploy",
|
|
183
|
+
"schedule": "0 3 * * *",
|
|
184
|
+
"prompt": "Build, test and deploy",
|
|
185
|
+
"matrix": {
|
|
186
|
+
"workspaceIds": ["frontend-id", "backend-id", "mobile-id"],
|
|
187
|
+
"strategy": "parallel",
|
|
188
|
+
"failureMode": "continue",
|
|
189
|
+
"aggregation": "summary",
|
|
190
|
+
"concurrency": 2,
|
|
191
|
+
"createAggregator": true,
|
|
192
|
+
"overrides": {
|
|
193
|
+
"mobile-id": { "qualityGate": "npm run test:mobile" }
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Each workspace gets a clone named `<parent>-matrix-<workspace>`. The parent never runs itself: it aggregates clone results into `success`, `error` or `partial`. Clones stay in sync with the parent when you edit it; running clones are never touched.
|
|
200
|
+
|
|
201
|
+
## GUI and dashboard
|
|
202
|
+
|
|
203
|
+
The OpenCode sidebar shows jobs, history, logs, dry-run, templates, import/export, concurrency limit and matrix grouping. The local web dashboard adds per-workspace summaries, matrix tabs, a pipeline view and metrics.
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
npm run build:gui # produces gui-experimental.cjs
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## How it works
|
|
210
|
+
|
|
211
|
+
```
|
|
212
|
+
src/
|
|
213
|
+
index.ts plugin lifecycle, agent tools, RPC
|
|
214
|
+
gui.tsx OpenCode sidebar panel
|
|
215
|
+
server.ts local web dashboard
|
|
216
|
+
core/
|
|
217
|
+
scheduler/ Windows / Linux / macOS backends
|
|
218
|
+
matrix.ts fan-out, aggregation, sync, cancel
|
|
219
|
+
record-history.ts history, retries, chains, matrix continuation
|
|
220
|
+
dry-run.ts pipeline simulation
|
|
221
|
+
lock.ts no-overlap protection
|
|
222
|
+
file-watcher.ts chokidar triggers
|
|
223
|
+
telegram.ts Telegram Bot API delivery
|
|
224
|
+
native-notify.ts Windows Toast / macOS / Linux notifications
|
|
225
|
+
db/ SQLite: tasks, history, metrics, settings
|
|
226
|
+
task-transfer.ts export / import / validation
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Job wrappers run `opencode run` in the task working directory, so project MCP servers are picked up automatically.
|
|
230
|
+
|
|
231
|
+
### Logon mode (Windows)
|
|
232
|
+
|
|
233
|
+
Tasks are **interactive only** by default: Task Scheduler starts them only while the user who created them is logged on, with the normal profile, drives and saved credentials. Pass `runWhenLoggedOff: true` to run a job without a logged-on user (`schtasks /ru SYSTEM`). Such a task runs in session 0 — no user profile, mapped drives, network shares or saved credentials — so jobs that need your environment may fail; test them with `dry_run` first. On Linux crontab already runs without a login, and a macOS launchd agent runs only inside a user session.
|
|
234
|
+
|
|
235
|
+
## Development
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
npm install
|
|
239
|
+
npm run build # tsc
|
|
240
|
+
npm run build:gui # vite
|
|
241
|
+
npm test # 58 test suites, 600+ checks
|
|
242
|
+
npm run test:en # same suites with the English locale
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
`npm run test:en` sets `OPENCODE_SCHEDULER_LOCALE=en` for every suite; the variable is a
|
|
246
|
+
service hook, not a user setting.
|
|
247
|
+
|
|
248
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
|
|
249
|
+
|
|
250
|
+
## Documentation
|
|
251
|
+
|
|
252
|
+
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — process model, modules, backends, data model.
|
|
253
|
+
- [docs/CONCEPT.md](docs/CONCEPT.md) — north-star concept: verifiable local-first orchestration (in Russian).
|
|
254
|
+
- [docs/FEATURES.md](docs/FEATURES.md) — full feature catalog with examples.
|
|
255
|
+
- [docs/FAQ.md](docs/FAQ.md) — recovery scenarios, webhook replay, operational answers.
|
|
256
|
+
- [docs/MIGRATION.md](docs/MIGRATION.md) — moving from cron, systemd, launchd or Task Scheduler.
|
|
257
|
+
- [docs/SAVINGS.md](docs/SAVINGS.md) — how the "Saved $" estimate is calculated.
|
|
258
|
+
- [CROSS_PLATFORM.md](CROSS_PLATFORM.md) — Windows / macOS / Linux differences and backends.
|
|
259
|
+
|
|
260
|
+
Translations: [Русский](docs/README.ru.md) · [中文](docs/README.zh.md).
|
|
261
|
+
|
|
262
|
+
## FAQ
|
|
263
|
+
|
|
264
|
+
**Does it work when OpenCode is closed?**
|
|
265
|
+
Yes, for cron and one-shot jobs. They are registered with the native OS scheduler, so they run without an open OpenCode window.
|
|
266
|
+
|
|
267
|
+
File (`file`), git (`git`) and MCP-event (`mcp-event`) triggers are watched by the plugin process (chokidar / git polling / the MCP event bus), so OpenCode must be running for those triggers to fire.
|
|
268
|
+
|
|
269
|
+
| Trigger | Runs without OpenCode? | Mechanism |
|
|
270
|
+
|---|---|---|
|
|
271
|
+
| `cron` | ✅ Yes | Native OS scheduler (Task Scheduler / launchd / crontab) |
|
|
272
|
+
| `once` | ✅ Yes | Native OS scheduler, one-shot registration |
|
|
273
|
+
| `file` | ❌ No | chokidar watcher inside the plugin process |
|
|
274
|
+
| `git` | ❌ No | Git polling inside the plugin process |
|
|
275
|
+
| `mcp-event` | ❌ No | MCP event bus inside the plugin process |
|
|
276
|
+
| `webhook` (`/api/hooks/:name`) | ❌ No | HTTP server inside the plugin process |
|
|
277
|
+
|
|
278
|
+
**Do jobs run when nobody is logged on?**
|
|
279
|
+
On Windows, only if you opt in with `runWhenLoggedOff: true`: the task is then registered as `schtasks /ru SYSTEM` and runs in session 0 without your profile, mapped drives or saved credentials. The default is interactive only — the job runs while the user is logged on. Linux crontab always runs without a login; a macOS launchd agent runs only inside a user session.
|
|
280
|
+
|
|
281
|
+
**Which platforms are supported?**
|
|
282
|
+
Windows (Task Scheduler), macOS (launchd) and Linux (crontab). Backend differences are documented in [CROSS_PLATFORM.md](CROSS_PLATFORM.md).
|
|
283
|
+
|
|
284
|
+
**Where does my data go?**
|
|
285
|
+
Nowhere. History, logs, metrics and settings are stored locally in SQLite. No telemetry, no accounts, no cloud.
|
|
286
|
+
|
|
287
|
+
**How do I get Telegram notifications?**
|
|
288
|
+
Create a bot with [@BotFather](https://t.me/BotFather), copy the token, send the bot a message and read `chat_id` from `getUpdates` (or use a group/channel ID). Paste both in the sidebar panel or run `manage_settings` with `notifications.telegram` (`enabled`, `botToken`, `chatId`, optional `parseMode`). To keep secrets out of `settings.json`, set `OPENCODE_SCHEDULER_TELEGRAM_BOT_TOKEN` and `OPENCODE_SCHEDULER_TELEGRAM_CHAT_ID` instead — environment values are used when the fields are empty. Use `send_notification` with `channel: "telegram"` to verify.
|
|
289
|
+
|
|
290
|
+
**Do I need an extra package for desktop notifications?**
|
|
291
|
+
No. Windows Toast (PowerShell/WinRT), macOS Notification Center (`osascript`) and Linux `notify-send` are called directly, so `node-notifier` is not required. Enable them with `notifications.native.enabled`.
|
|
292
|
+
|
|
293
|
+
**Can I silence notifications at night?**
|
|
294
|
+
Yes. Set `notifications.quietHours` (`enabled`, `from`, `to` in `HH:MM`). During the window successful and `partial` runs are suppressed, while failures and timeouts are always delivered.
|
|
295
|
+
|
|
296
|
+
**How do I store secrets?**
|
|
297
|
+
Use `manage_secrets` (or the **🔐 Secrets** panel in the sidebar) to create an encrypted secret. Secrets are stored in `<PLUGIN_DIR>/secrets.json` with AES-256-GCM and a key file (`secrets.key`; mode 0600 on POSIX, an ACL granting only the current Windows user on Windows). In task `env`, reference a secret as `${secret:NAME}` — the value is substituted at run time and masked in logs, history and audit. The secret name can also be set via `manage_settings` → `notifications.telegram.botToken` left empty and `OPENCODE_SCHEDULER_TELEGRAM_BOT_TOKEN` env var instead.
|
|
298
|
+
|
|
299
|
+
**Can I see who changed what?**
|
|
300
|
+
Yes. The audit log (`get_audit_log` tool, **Audit log** panel, `GET /api/audit`) records every mutation — task create/update/delete/run, settings, templates, profiles, workspaces, secrets, import, history cleanup — with actor (mcp/gui/http), source, timestamp and redacted details. Retention defaults to 90 days / 10 000 records.
|
|
301
|
+
|
|
302
|
+
**How is this different from `experimental.schedules`?**
|
|
303
|
+
The built-in scheduler runs jobs while OpenCode is open. This plugin uses the native OS scheduler and adds DAG pipelines, matrix builds, quality gates, webhooks and observability.
|
|
304
|
+
|
|
305
|
+
**Can jobs run in other repositories?**
|
|
306
|
+
Yes. Workspaces point at project paths, and a matrix build runs one template across several workspaces at once.
|
|
307
|
+
|
|
308
|
+
## Roadmap
|
|
309
|
+
|
|
310
|
+
- [ROADMAP.md](ROADMAP.md) — sprint history and next sprints.
|
|
311
|
+
- [ROADMAP-STRATEGY.md](ROADMAP-STRATEGY.md) — positioning and 6-month plan.
|
|
20
312
|
|
|
21
|
-
|
|
22
|
-
so existing installs keep working. Until then, treat this version as a placeholder.
|
|
313
|
+
## License
|
|
23
314
|
|
|
24
|
-
|
|
315
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# 🎯 Стратегический роадмап — agent-steward
|
|
2
|
+
|
|
3
|
+
> Цель: **стать лучшим планировщиком и оркестратором для OpenCode, оставаясь бесплатным и open source.**
|
|
4
|
+
> Тактический спринт-план — в [ROADMAP.md](./ROADMAP.md), выпущенные изменения — в [CHANGELOG.md](./CHANGELOG.md).
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Позиционирование
|
|
9
|
+
|
|
10
|
+
**Мы не «cron для OpenCode». Мы — локальная платформа оркестрации AI-задач:**
|
|
11
|
+
расписание + зависимости (DAG) + матрицы (fan-out) + политики качества + наблюдаемость.
|
|
12
|
+
|
|
13
|
+
| Принцип | Что это значит на практике |
|
|
14
|
+
|---|---|
|
|
15
|
+
| **Бесплатно навсегда** | MIT, без SaaS, без телеметрии, без «pro»-функций |
|
|
16
|
+
| **Локально по умолчанию** | Данные, история и логи — на машине пользователя |
|
|
17
|
+
| **Open source-first** | Публичный roadmap, CI на 3 ОС, английская документация |
|
|
18
|
+
| **Оркестрация, а не таймер** | Ров — DAG, матрицы, Quality Gates, наблюдаемость. Cron скопируют за неделю |
|
|
19
|
+
|
|
20
|
+
**Текущая точка (1.5.3):**
|
|
21
|
+
|
|
22
|
+
- опубликован в npm, CI зелёный на Windows / macOS / Linux;
|
|
23
|
+
- 26 инструментов агента — паритет с RPC-поверхностью;
|
|
24
|
+
- локальный триаж + shadow mode, `manage_local_ai` инструмент + блок настроек в GUI — есть;
|
|
25
|
+
- один-shot запуски, непрерывность сессий, профили, webhooks, Telegram и нативные toast, тихие часы, Prometheus и OTLP — есть;
|
|
26
|
+
- зашифрованные секреты (${secret:NAME}) и журнал аудита — есть;
|
|
27
|
+
- английский README и `docs/` — основные, русский синхронизирован в `docs/README.ru.md`.
|
|
28
|
+
|
|
29
|
+
**Чего ещё нет:** pipeline-as-code, Docker-runner, approvals и remote runners.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Горизонт 0–1 месяц: доверие и тишина
|
|
34
|
+
|
|
35
|
+
Сделано: уведомления (1.3.0), секреты и аудит (1.4.0), git-триггеры и окна (1.5.0).
|
|
36
|
+
|
|
37
|
+
### 1. i18n-фундамент (P1) — 1.5.1
|
|
38
|
+
|
|
39
|
+
Все пользовательские строки в `locales/en.json` + `locales/ru.json`, ICU-подмножество на `Intl.PluralRules`, паритет ключей в CI, RU по умолчанию. Без этого нельзя масштабировать аудиторию.
|
|
40
|
+
|
|
41
|
+
### 2. Security slice A (P1) — 1.5.2
|
|
42
|
+
|
|
43
|
+
Enforced `allowedTools` / `deniedTools` вместо advisory, scoped-инъекция `${secret:NAME}`, аудит `tool.blocked`. До запуска флагмана приватности: обещание не должно расходиться с реализацией.
|
|
44
|
+
|
|
45
|
+
### 3. Локальный помощник v1 (P1) — 1.5.3
|
|
46
|
+
|
|
47
|
+
Триаж уведомлений локальной моделью с fail-open на правила, shadow mode 14 дней, `manage_local_ai`, bench. Меньше шума без потери важного — и работает без модели.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Горизонт 2–4 месяца: CI/CD-оркестрация
|
|
52
|
+
|
|
53
|
+
> **Черновик.** Нумерация версий здесь отстала от `ROADMAP.md` и не обновляется: актуальная карта версий и спринтов — в `ROADMAP.md` (раздел «Карта версий»). При расхождении верить `ROADMAP.md`.
|
|
54
|
+
|
|
55
|
+
### 4. Локальный помощник v2 (P2) — 1.5.4
|
|
56
|
+
|
|
57
|
+
Саммари логов в 3 строки, дедуп на эмбеддингах, GUI-wizard, счётчик экономии с пометкой «оценка».
|
|
58
|
+
|
|
59
|
+
### 5. Pipeline-as-code (P2) — 1.5.5
|
|
60
|
+
|
|
61
|
+
`opencode.pipeline.yaml` в репозитории + CLI `opencode pipeline validate|run|export`. DAG, матрицы и Quality Gates описываются файлом, который можно ревьюить в PR.
|
|
62
|
+
|
|
63
|
+
**Почему:** это водораздел между «планировщиком» и «оркестратором». Ни один плагин экосистемы пока не умеет pipeline-as-code.
|
|
64
|
+
|
|
65
|
+
### 6. Worktree-изоляция и guard-условия (P2) — 1.5.6
|
|
66
|
+
|
|
67
|
+
Одноразовый `git worktree` на запуск, политика очистки, shell- и семантические guard-условия, статус `skipped`. 80% ценности безопасного fan-out без инфраструктуры Docker.
|
|
68
|
+
|
|
69
|
+
### 7. Экономика v2 (P2) — 1.5.7
|
|
70
|
+
|
|
71
|
+
Бюджеты на день/неделю с авто-паузой и алертом, per-task token budgets, token efficiency score, прогноз, Grafana JSON, local vs cloud.
|
|
72
|
+
|
|
73
|
+
### 8. Docker runner (P3) — 1.5.8
|
|
74
|
+
|
|
75
|
+
Локальный процесс, Docker, SSH-хост. Задача описывает *что* делать, runner — *где*. Изоляцию не изобретаем: Docker / Landstrip. Opt-in, по умолчанию выключен.
|
|
76
|
+
|
|
77
|
+
### 9. Durable DAG (P1 для 1.6.0) — 1.5.9
|
|
78
|
+
|
|
79
|
+
Персистентная state-машина прогона, resume после краша, идемпотентные шаги, DLQ, chaos `kill -9` в nightly.
|
|
80
|
+
|
|
81
|
+
### 10. Rename-only + daemon + config v2 (P2) — 1.5.10
|
|
82
|
+
|
|
83
|
+
Переименование в `agent-steward` отдельным релизом без фич (старый пакет живой, тонкий re-export), `scheduler.backend: native|daemon|off|auto`, автомиграция конфига.
|
|
84
|
+
|
|
85
|
+
### 11. Approvals, окружения, артефакты (MAJOR) — 1.6.0
|
|
86
|
+
|
|
87
|
+
Ручное подтверждение перед деплоем, dev / staging / prod, отчёты и coverage как артефакты запуска, docs-сайт и 4 локали.
|
|
88
|
+
|
|
89
|
+
### 12. Remote runners (P3)
|
|
90
|
+
|
|
91
|
+
Агент на удалённой машине, центральный дашборд, очередь и конкурентность на кластере. Делать после подтверждения спроса.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Ров, который не скопируют за неделю
|
|
96
|
+
|
|
97
|
+
1. **Windows-супервизия.** Конкурент `opencode-scheduler` прямо предупреждает, что на Windows не гарантирует no-overlap и таймауты; у нас обёртки, lock-файлы, crash recovery и единая модель на трёх ОС.
|
|
98
|
+
2. **OpenCode v2.** Часть плагинов всё ещё на устаревшем конфиге `plugin` и не подтверждает совместимость с v2.
|
|
99
|
+
3. **Оркестрация.** DAG, матрицы, Quality Gates, `partial`-статусы, dry-run и история — этого нет ни у одного планировщика экосистемы.
|
|
100
|
+
4. **Локальность.** Никаких облаков и аккаунтов — конкуренты с SaaS-моделью сюда не пойдут.
|
|
101
|
+
|
|
102
|
+
**Чего не делаем:** свой sandbox, свою CI-платформу, хостинг агентов, платные тарифы.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Метрики успеха
|
|
107
|
+
|
|
108
|
+
| Метрика | Сейчас (1.5.1) | Через 2 мес | Через 6 мес |
|
|
109
|
+
|---|---|---|---|
|
|
110
|
+
| npm latest | 1.5.1 | регулярные патчи | 1.6.x |
|
|
111
|
+
| CI на 3 ОС | ✅ | ✅ | ✅ |
|
|
112
|
+
| Покрытие RPC инструментами агента | 100% | 100% | 100% |
|
|
113
|
+
| Telegram / toast | ✅ | ✅ | ✅ |
|
|
114
|
+
| Secrets / audit | ✅ | ✅ | ✅ |
|
|
115
|
+
| Git-триггеры | ✅ | ✅ | ✅ |
|
|
116
|
+
| Pipeline-as-code | ❌ | прототип | ✅ |
|
|
117
|
+
| Docker runner | ❌ | ❌ | ✅ |
|
|
118
|
+
| Загрузки npm / мес | первые | 300+ | 1500+ |
|
|
119
|
+
| GitHub stars | единицы | 100+ | 500+ |
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Риски и триггеры пересмотра
|
|
124
|
+
|
|
125
|
+
| Риск | Триггер | Ответ |
|
|
126
|
+
|---|---|---|
|
|
127
|
+
| Нативный scheduler OpenCode поглощает cron | Стабильный API расписаний | Режим `nativeScheduler`, акцент на DAG / матрицы / политики |
|
|
128
|
+
| Похожий плагин с GUI и CI/CD | Релиз конкурента | Ускорить pipeline-as-code и Docker runner |
|
|
129
|
+
| Bus factor = 1 | >5 issues без ответа | Сузить scope, заморозить P3, искать мейнтейнеров |
|
|
130
|
+
| API OpenCode v2 меняется | Breaking change в `@opencode/plugin` | Держать адаптер, следить за релизами, CI ловит первым |
|
|
131
|
+
| Расползание scope | Спринт длиннее 2 недель | Резать на вертикальные срезы, P3 — в бэклог |
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Ближайшие две недели
|
|
136
|
+
|
|
137
|
+
1. i18n-фундамент (1.5.1) — каталоги локалей, паритет ключей в CI, RU по умолчанию.
|
|
138
|
+
2. Security slice A (1.5.2) — спайк по правам агента, затем enforced `allowedTools` / `deniedTools`.
|
|
139
|
+
3. Docker runner — после подтверждения спроса.
|
|
140
|
+
|
|
141
|
+
**Критерий месяца:** пользователь ставит плагин одной командой, получает уведомление в Telegram о падении задачи, токены и доступы не лежат открытым текстом в `tasks.json`, а интерфейс говорит на его языке.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Долгосрочное видение
|
|
146
|
+
|
|
147
|
+
Путь от плагина к фреймворку описан в [docs/CONCEPT.md](./docs/CONCEPT.md) (§13): локальный интеллект + мультиагентная оркестрация + абстракция слоя исполнения. Этот тактический роадмап является реализацией первых двух этапов — глубокой интеграции с OpenCode v2 и подготовки к абстракции Agent Executor Interface.
|