opencode-windows-scheduler 1.5.2 → 1.5.5
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 +107 -2
- package/CROSS_PLATFORM.md +107 -71
- package/LICENSE +21 -21
- package/README.md +74 -26
- package/ROADMAP-STRATEGY.md +11 -4
- package/ROADMAP.md +322 -112
- package/dist/core/analytics.d.ts +3 -0
- package/dist/core/analytics.d.ts.map +1 -1
- package/dist/core/analytics.js +4 -0
- package/dist/core/audit.d.ts +2 -1
- package/dist/core/audit.d.ts.map +1 -1
- package/dist/core/audit.js +32 -1
- package/dist/core/cron-to-schtasks.d.ts.map +1 -1
- package/dist/core/cron-to-schtasks.js +21 -4
- package/dist/core/file-watcher.d.ts.map +1 -1
- package/dist/core/file-watcher.js +16 -1
- package/dist/core/git-trigger.d.ts +4 -2
- package/dist/core/git-trigger.d.ts.map +1 -1
- package/dist/core/git-trigger.js +34 -16
- 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 +14 -0
- package/dist/core/lock.d.ts.map +1 -1
- package/dist/core/lock.js +81 -4
- package/dist/core/matrix.d.ts.map +1 -1
- package/dist/core/matrix.js +3 -2
- package/dist/core/native-notify.d.ts.map +1 -1
- package/dist/core/native-notify.js +3 -0
- package/dist/core/one-shot.d.ts +7 -1
- package/dist/core/one-shot.d.ts.map +1 -1
- package/dist/core/one-shot.js +15 -2
- 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/ps-wrapper.d.ts +9 -30
- package/dist/core/ps-wrapper.d.ts.map +1 -1
- package/dist/core/ps-wrapper.js +477 -108
- package/dist/core/record-history.d.ts +11 -0
- package/dist/core/record-history.d.ts.map +1 -1
- package/dist/core/record-history.js +106 -4
- 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.js +7 -3
- package/dist/core/schedule-v2.js +1 -1
- package/dist/core/scheduler/index.d.ts +13 -1
- package/dist/core/scheduler/index.d.ts.map +1 -1
- package/dist/core/scheduler/index.js +35 -4
- package/dist/core/scheduler/linux.d.ts +4 -1
- package/dist/core/scheduler/linux.d.ts.map +1 -1
- package/dist/core/scheduler/linux.js +53 -20
- package/dist/core/scheduler/mac.d.ts +2 -1
- package/dist/core/scheduler/mac.d.ts.map +1 -1
- package/dist/core/scheduler/mac.js +24 -6
- package/dist/core/scheduler/posix.d.ts +1 -1
- package/dist/core/scheduler/posix.d.ts.map +1 -1
- package/dist/core/scheduler/posix.js +2 -2
- package/dist/core/scheduler/registry.d.ts +3 -2
- package/dist/core/scheduler/registry.d.ts.map +1 -1
- package/dist/core/scheduler/registry.js +6 -5
- package/dist/core/scheduler/windows.d.ts +49 -1
- package/dist/core/scheduler/windows.d.ts.map +1 -1
- package/dist/core/scheduler/windows.js +219 -34
- package/dist/core/secrets.d.ts +5 -3
- package/dist/core/secrets.d.ts.map +1 -1
- package/dist/core/secrets.js +86 -8
- 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/session.d.ts +11 -3
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +34 -5
- 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/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 +10 -0
- package/dist/core/telegram.d.ts.map +1 -1
- package/dist/core/telegram.js +228 -47
- 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 +15 -3
- package/dist/core/wrappers/bash.d.ts.map +1 -1
- package/dist/core/wrappers/bash.js +153 -120
- package/dist/db/history-repo.d.ts +1 -1
- package/dist/db/history-repo.d.ts.map +1 -1
- package/dist/db/history-repo.js +29 -14
- package/dist/db/schema.d.ts +1 -1
- package/dist/db/schema.d.ts.map +1 -1
- package/dist/db/schema.js +31 -0
- package/dist/history.d.ts +2 -2
- package/dist/history.d.ts.map +1 -1
- package/dist/history.js +3 -3
- package/dist/i18n.d.ts +25 -2
- package/dist/i18n.d.ts.map +1 -1
- package/dist/i18n.js +75 -10
- package/dist/index.d.ts +66 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +527 -68
- package/dist/integrations.d.ts +9 -1
- package/dist/integrations.d.ts.map +1 -1
- package/dist/integrations.js +34 -6
- package/dist/notifications.d.ts +30 -2
- package/dist/notifications.d.ts.map +1 -1
- package/dist/notifications.js +289 -10
- package/dist/profiles.d.ts +1 -1
- package/dist/profiles.d.ts.map +1 -1
- package/dist/profiles.js +21 -3
- package/dist/rpc.d.ts +401 -5
- package/dist/rpc.d.ts.map +1 -1
- package/dist/rpc.js +138 -5
- package/dist/server.d.ts +20 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +136 -14
- package/dist/settings.d.ts +167 -3
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +322 -3
- package/dist/task-transfer.d.ts +8 -1
- package/dist/task-transfer.d.ts.map +1 -1
- package/dist/task-transfer.js +2 -2
- package/dist/types.d.ts +8 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +23 -5
- package/dist/workspaces.d.ts +9 -0
- package/dist/workspaces.d.ts.map +1 -1
- package/dist/workspaces.js +25 -0
- package/docs/ARCHITECTURE.md +48 -28
- 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 +141 -44
- package/docs/FEATURES.zh.md +655 -0
- package/docs/LOCAL-AI.md +300 -0
- package/docs/MIGRATION.md +17 -0
- package/docs/README.ru.md +22 -16
- package/docs/README.zh.md +286 -0
- package/docs/SAVINGS.md +61 -0
- package/docs/SAVINGS.ru.md +60 -0
- package/docs/SAVINGS.zh.md +52 -0
- package/docs/ZH-LOCALE-PLAN.md +324 -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 +8 -8
- package/locales/en.json +85 -0
- package/locales/ru.json +85 -0
- package/locales/zh.json +780 -0
- package/package.json +31 -7
- package/scripts/bench-local.mjs +321 -0
- package/scripts/check-zh-locale.mjs +218 -0
- package/scripts/run-tests.mjs +236 -0
- package/scripts/spike-local-structured.mjs +182 -0
- package/scripts/test-locale.mjs +4 -3
- package/skills/scheduled-job-best-practices/SKILL.md +6 -3
- package/skills/scheduled-job-best-practices/references/recipes.md +40 -0
- package/src/core/analytics.ts +10 -0
- package/src/core/audit.ts +39 -1
- package/src/core/cron-to-schtasks.ts +23 -4
- package/src/core/file-watcher.ts +20 -1
- package/src/core/git-trigger.ts +34 -16
- package/src/core/local-ai.ts +173 -0
- package/src/core/lock.ts +88 -3
- package/src/core/matrix.ts +5 -1
- package/src/core/native-notify.ts +3 -0
- package/src/core/one-shot.ts +18 -2
- package/src/core/permissions.ts +200 -0
- package/src/core/ps-wrapper.ts +492 -108
- package/src/core/record-history.ts +111 -4
- package/src/core/savings.ts +150 -0
- package/src/core/schedule-gate.ts +9 -3
- package/src/core/schedule-v2.ts +1 -1
- package/src/core/scheduler/index.ts +41 -3
- package/src/core/scheduler/linux.ts +67 -22
- package/src/core/scheduler/mac.ts +24 -7
- package/src/core/scheduler/posix.ts +2 -2
- package/src/core/scheduler/registry.ts +7 -5
- package/src/core/scheduler/windows.ts +237 -32
- package/src/core/secrets.ts +101 -7
- package/src/core/self-analysis.ts +744 -0
- package/src/core/session.ts +40 -5
- package/src/core/shutdown.ts +69 -0
- package/src/core/summary.ts +318 -0
- package/src/core/telegram.ts +266 -55
- 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 +181 -138
- package/src/db/history-repo.ts +31 -18
- package/src/db/schema.ts +31 -0
- package/src/gui.tsx +551 -14
- package/src/history.ts +7 -3
- package/src/i18n.ts +87 -13
- package/src/index.ts +649 -71
- package/src/integrations.ts +50 -6
- package/src/notifications.ts +468 -5
- package/src/profiles.ts +21 -3
- package/src/rpc.ts +143 -5
- package/src/server.ts +135 -16
- package/src/settings.ts +582 -5
- package/src/task-transfer.ts +10 -3
- package/src/types.ts +24 -5
- package/src/workspaces.ts +22 -0
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# 跨平台:Windows → macOS → Linux
|
|
2
|
+
|
|
3
|
+
插件已不再绑定 `schtasks`。调度器被抽象成一层接口,有三种实现,运行包装脚本按目标操作系统生成。
|
|
4
|
+
|
|
5
|
+
Translations: [English](../CROSS_PLATFORM.md) · [Русский](CROSS_PLATFORM.ru.md)
|
|
6
|
+
|
|
7
|
+
## 架构
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
src/
|
|
11
|
+
index.ts # 工具、RPC、插件生命周期
|
|
12
|
+
gui.tsx # GUI 面板(标题来自 RPC)
|
|
13
|
+
server.ts # Web 仪表盘(动态标题)
|
|
14
|
+
core/
|
|
15
|
+
scheduler/
|
|
16
|
+
types.ts # SchedulerBackend、CreateTaskOptions、RunTaskResult
|
|
17
|
+
index.ts # 工厂 createSchedulerBackend() + getSchedulerTitle()
|
|
18
|
+
windows.ts # WindowsScheduler (schtasks)
|
|
19
|
+
linux.ts # LinuxScheduler (crontab)
|
|
20
|
+
mac.ts # MacScheduler (launchd / LaunchAgents)
|
|
21
|
+
posix.ts # Linux/macOS 共享基类(任务注册表)
|
|
22
|
+
registry.ts # POSIX 后端的持久化任务注册表
|
|
23
|
+
logs.ts # 跨平台任务日志读取
|
|
24
|
+
wrappers/
|
|
25
|
+
bash.ts # Linux/macOS 的 .sh 包装脚本生成器
|
|
26
|
+
ps-wrapper.ts # Windows 的 .ps1/.cmd 包装脚本(未变)
|
|
27
|
+
record-history.ts # 指标/历史 + 重试/链式任务(通过后端)
|
|
28
|
+
cron-to-schtasks.ts # cron → schtasks(仅 Windows)
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### 接口
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
interface SchedulerBackend {
|
|
35
|
+
readonly platform: NodeJS.Platform;
|
|
36
|
+
readonly title: string; // "Windows 任务计划程序" / "OpenCode Scheduler"
|
|
37
|
+
createTask(options: CreateTaskOptions): Promise<void>;
|
|
38
|
+
deleteTask(name: string): Promise<void>;
|
|
39
|
+
runTask(name: string): Promise<RunTaskResult>;
|
|
40
|
+
listTasks(): Promise<ScheduledTaskInfo[]>;
|
|
41
|
+
pauseTask(name: string): Promise<void>;
|
|
42
|
+
resumeTask(name: string): Promise<void>;
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
工厂按 `process.platform` 选择实现:
|
|
47
|
+
`win32 → WindowsScheduler`,`darwin → MacScheduler`,其余 → `LinuxScheduler`。
|
|
48
|
+
|
|
49
|
+
## 各操作系统的运行方式
|
|
50
|
+
|
|
51
|
+
### Windows(行为未变)
|
|
52
|
+
- 任务通过 `schtasks` 注册到 Windows 任务计划程序的 `\OpenCode\windows-scheduler\` 文件夹。
|
|
53
|
+
- 包装脚本:`run-task.ps1` 加每个任务专属的 `run-<name>.cmd`,位于 `%APPDATA%\opencode\windows-scheduler\wrapper`。
|
|
54
|
+
- 日志:`%APPDATA%\opencode\windows-scheduler\logs\<name>.log`。
|
|
55
|
+
- cron 会转换成 schtasks(`convertCronToSchTasks`)——支持与之前相同的模板集合。
|
|
56
|
+
|
|
57
|
+
### Linux
|
|
58
|
+
- 任务保存在受管 `crontab` 块中:
|
|
59
|
+
```
|
|
60
|
+
# >>> opencode-scheduler >>>
|
|
61
|
+
# task: my-task
|
|
62
|
+
*/5 * * * * /bin/bash '/…/wrapper/run-my-task.sh' >> '/…/logs/my-task.log' 2>&1
|
|
63
|
+
# <<< opencode-scheduler <<<
|
|
64
|
+
```
|
|
65
|
+
- 暂停 = 带 `# PAUSED: ` 前缀的行(块会从注册表重建)。
|
|
66
|
+
- `file` 触发器的任务不会进入 crontab——由插件的 FileWatchManager 启动。
|
|
67
|
+
- 包装脚本:`~/.config/opencode/windows-scheduler/wrapper/run-<name>.sh`(chmod 0755)。
|
|
68
|
+
- 支持完整 cron 语法(与 Windows 不同),因为 crontab 原生支持。
|
|
69
|
+
- 删除/重建只触及自己的块,`crontab` 的其他行不受影响。
|
|
70
|
+
|
|
71
|
+
### macOS
|
|
72
|
+
- 任务是 LaunchAgent plist:`~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`。
|
|
73
|
+
- 调度:`* * * * *` 和 `*/N` 使用 `StartInterval`,`M * * * *`、`M H * * *`、`M H * * D`
|
|
74
|
+
使用 `StartCalendarInterval`。
|
|
75
|
+
- 暂停 = `launchctl unload -w`,恢复 = `launchctl load -w`。
|
|
76
|
+
- 包装脚本与 Linux 相同的 `.sh`;配置路径:
|
|
77
|
+
`~/.config/opencode/windows-scheduler/`(或 `$XDG_CONFIG_HOME`)。
|
|
78
|
+
|
|
79
|
+
### 共享 POSIX 包装脚本(`.sh`)
|
|
80
|
+
- `cd` 到工作目录,用文件中的提示词执行 `opencode run`。
|
|
81
|
+
- 日志通过 `>>` 追加,并带时间戳。
|
|
82
|
+
- 通过原子 `mkdir` 加锁——防止并行运行。
|
|
83
|
+
- 超时:子进程 + 看门狗(先 `TERM`,再 `KILL`)。
|
|
84
|
+
- Quality Gate:`bash -lc "<命令>"`(相当于 Windows 上的 `cmd.exe /c`)。
|
|
85
|
+
- 指标:`node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"`——
|
|
86
|
+
与 PowerShell 包装脚本相同的契约,因此历史/指标/重试/链式任务在各平台通用。
|
|
87
|
+
- `PATH` 追加 `/opt/homebrew/bin`、`/usr/local/bin`、`~/.local/bin`、`~/.bun/bin`。
|
|
88
|
+
|
|
89
|
+
## 功能矩阵
|
|
90
|
+
|
|
91
|
+
| 能力 | Windows | Linux | macOS |
|
|
92
|
+
|---|---|---|---|
|
|
93
|
+
| 调度后端 | `schtasks` | `crontab` | `launchd` LaunchAgents |
|
|
94
|
+
| 原生 cron 子集 | `* * * * *`、`*/N * * * *`(N ≤ 1439,60 % N = 0)、`M * * * *`、`M H * * *`、`M H * * D` | 完整 cron | 与 Windows 相同的子集 |
|
|
95
|
+
| 其他 cron 表达式 | 分钟轮询 + schedule gate | 原生 cron | 分钟轮询 + schedule gate |
|
|
96
|
+
| 月/周字段中的 `*/N` | 非原生 → 轮询 | 原生 | 非原生 → 轮询 |
|
|
97
|
+
| 暂停 / 恢复 | `schtasks /change /disable` / `/enable` | 托管块中的 `# PAUSED:` 行 | `launchctl unload -w` / `load -w` |
|
|
98
|
+
| 文件触发器 | 进程内 `FileWatchManager` | 相同 | 相同 |
|
|
99
|
+
| 任务包装脚本 | `.cmd` + `.ps1` | `.sh` | `.sh` |
|
|
100
|
+
| 日志 | `%APPDATA%\opencode\windows-scheduler\logs` | `~/.config/opencode/windows-scheduler/logs` | 与 Linux 相同 |
|
|
101
|
+
| `secrets.key` 保护 | `icacls`(仅所有者)+ `chmod` 回退 | `chmod 0600` | `chmod 0600` |
|
|
102
|
+
| 仪表盘 | `127.0.0.1`,动态标题 | 相同 | 相同 |
|
|
103
|
+
| DAG / matrix / quality gates / 通知 | 插件内,与操作系统无关 | 相同 | 相同 |
|
|
104
|
+
|
|
105
|
+
### 折衷
|
|
106
|
+
|
|
107
|
+
1. **分钟轮询。** 原生子集之外的 cron 表达式,以及使用非系统 IANA 时区的任务,
|
|
108
|
+
由操作系统调度器每分钟启动一次;`schedule-gate` 决定是否真正执行。
|
|
109
|
+
代价是每个任务每分钟一个短生命周期的包装进程。
|
|
110
|
+
2. **`M H */N * *` 故意不转换为 `schtasks /sc DAILY /mo N`。**
|
|
111
|
+
cron 从每月 1 日开始计数,并在月初重置;`/mo N` 从任务创建日期开始计数,
|
|
112
|
+
不会在月初重置。两者并不等价,因此该表达式保持轮询模式。
|
|
113
|
+
若要原生支持,应使用 `MONTHLY` 加显式 `/d` 列表,而不是 `DAILY /mo N`。
|
|
114
|
+
3. **DST。** 网关按本地墙上时间工作。不存在的时间(春季前进)会被跳过;
|
|
115
|
+
有歧义的时间(秋季回拨)在第一次出现时执行。
|
|
116
|
+
4. **Windows 上的 `*/N * * * *`** 仅在 `60 % N = 0` 且 `N ≤ 1439` 时原生支持。
|
|
117
|
+
否则回退到轮询:`schtasks /mo N` 从创建时刻计数,而 cron 从整点开始计数。
|
|
118
|
+
5. **POSIX 包装脚本、crontab 和 launchd 尚未在真实 Linux/macOS 主机上执行**
|
|
119
|
+
(见“限制”);语法和转义仅由测试覆盖。
|
|
120
|
+
|
|
121
|
+
## GUI 与仪表盘
|
|
122
|
+
- 标题是动态的:Windows 上为「Windows 任务计划程序」,macOS/Linux 上为「OpenCode Scheduler」。
|
|
123
|
+
- 标题来自 RPC 方法 `get_platform` → `{ platform, title }`。
|
|
124
|
+
- 标题同时用于 GUI 面板、错误回退面板和仪表盘的 `<title>/<h1>`。
|
|
125
|
+
- 按钮、状态、表格、DAG 和指标与操作系统无关。
|
|
126
|
+
- 工具描述(`schedule_task` 等)会替换为实际调度器名称。
|
|
127
|
+
|
|
128
|
+
## 构建与检查
|
|
129
|
+
- `npm run build` — 通过,无错误。
|
|
130
|
+
- `npm run build:gui` — 通过(`gui-experimental.cjs`,约 47.7 kB)。
|
|
131
|
+
- 运行时已验证:
|
|
132
|
+
- win32/darwin/linux 的标题;
|
|
133
|
+
- 多个表达式上的 `cronToLaunchdSchedule`;
|
|
134
|
+
- Windows 上真实的 `listTasks()`——返回短任务名(无前缀);
|
|
135
|
+
- `shellQuote` 转义(引号、空格、西里尔字母);
|
|
136
|
+
- `dist/index.js` 可导入,`dist` 不直接引用 `schtasks.js`。
|
|
137
|
+
|
|
138
|
+
## 限制与需要在真实机器上验证的内容
|
|
139
|
+
1. `.sh` 包装脚本和 crontab/launchd **从未实际执行**——当前 Windows 机器没有 `bash`/WSL。
|
|
140
|
+
语法和转义是手工检查的;仍需在 Linux 和 macOS 上跑一遍。
|
|
141
|
+
2. cron → launchd 支持与 Windows 相同的有限模板集合
|
|
142
|
+
(`* * * * *`、`*/N * * * *`、`M * * * *`、`M H * * *`、`M H * * D`)。
|
|
143
|
+
Linux 上支持完整 cron。
|
|
144
|
+
3. Windows 任务前缀(`\OpenCode\windows-scheduler\`)和插件 id 为向后兼容而保留。
|
|
145
|
+
4. `src/schtasks.ts` 保留为旧脚本(`test-create.cjs`、`test-run.cjs`)的薄垫片;
|
|
146
|
+
所有逻辑现在都在 `core/scheduler/windows.ts`。
|
package/docs/FAQ.md
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# FAQ
|
|
2
|
+
|
|
3
|
+
Frequently asked questions and recovery scenarios. The English version of the
|
|
4
|
+
secrets section is also in [FEATURES.md](FEATURES.md#recovering-a-quarantined-secrets-store).
|
|
5
|
+
|
|
6
|
+
Translations: [Русский](FAQ.ru.md) · [中文](FAQ.zh.md)
|
|
7
|
+
|
|
8
|
+
## Contents
|
|
9
|
+
|
|
10
|
+
- [Recovering secrets after a `.corrupt-*` quarantine](#recovering-secrets-after-a-corrupt--quarantine)
|
|
11
|
+
- [Webhook triggers: can a request be replayed?](#webhook-triggers-can-a-request-be-replayed)
|
|
12
|
+
|
|
13
|
+
## Recovering secrets after a `.corrupt-*` quarantine
|
|
14
|
+
|
|
15
|
+
Quarantine triggers when `secrets.json` cannot be parsed (an interrupted write or
|
|
16
|
+
manual editing). The file is **not deleted** — it is renamed to
|
|
17
|
+
`secrets.json.corrupt-<timestamp>` next to the original. This is a side effect of a
|
|
18
|
+
read operation; recovery is **manual by design** so that no automatic rewrite can
|
|
19
|
+
destroy data.
|
|
20
|
+
|
|
21
|
+
Recovery steps:
|
|
22
|
+
|
|
23
|
+
1. Find the file in the plugin directory: `%APPDATA%\opencode\windows-scheduler\`
|
|
24
|
+
(Windows) or `~/.config/opencode/windows-scheduler/` (macOS/Linux, or
|
|
25
|
+
`$XDG_CONFIG_HOME`).
|
|
26
|
+
2. Open it in an editor: it is usually truncated JSON. Fix the syntax.
|
|
27
|
+
3. Copy the fixed file back as `secrets.json` (keep the `.corrupt-*` copy as a
|
|
28
|
+
backup) and verify with `manage_secrets` (`action: "list"`).
|
|
29
|
+
4. If the file cannot be repaired, re-set the secrets (`manage_secrets`,
|
|
30
|
+
`action: "set"`). Values encrypted with a lost `secrets.key` cannot be recovered
|
|
31
|
+
— re-enter them.
|
|
32
|
+
5. Rare case: the rename failed and writes stay blocked ("Writing new secrets is
|
|
33
|
+
blocked"). Move the broken file away manually, then re-set the secrets.
|
|
34
|
+
|
|
35
|
+
## Webhook triggers: can a request be replayed?
|
|
36
|
+
|
|
37
|
+
Yes — in both remaining authentication modes requests are replayable, so replay
|
|
38
|
+
protection is the sender's responsibility:
|
|
39
|
+
|
|
40
|
+
- **Signature without `timestampToleranceSeconds` (= 0, legacy).** The HMAC covers
|
|
41
|
+
only the body, so an intercepted request can be replayed forever. Set a non-zero
|
|
42
|
+
tolerance and send `X-Scheduler-Timestamp`: the signature then covers
|
|
43
|
+
`<timestamp>.<body>` and a request outside the window is rejected.
|
|
44
|
+
- **Token-only mode.** A token is also replayable — the scheduler cannot tell a
|
|
45
|
+
repeat from an attack. If you cannot switch to signatures: keep the token in CI
|
|
46
|
+
secrets, rotate it regularly, issue one token per task, and make the task
|
|
47
|
+
idempotent.
|
|
48
|
+
- **GitHub Actions** does not send `X-Scheduler-Timestamp` itself, so
|
|
49
|
+
`X-Hub-Signature-256` runs in legacy mode. Sign `<timestamp>.<body>` in a separate
|
|
50
|
+
workflow step with the shared secret.
|
|
51
|
+
- The scheduler keeps no replay cache — deduplicating unique requests is the
|
|
52
|
+
sender's responsibility.
|
package/docs/FAQ.ru.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# FAQ
|
|
2
|
+
|
|
3
|
+
Частые вопросы и восстановительные сценарии. Английская версия этого раздела —
|
|
4
|
+
в [FEATURES.md](FEATURES.md#recovering-a-quarantined-secrets-store).
|
|
5
|
+
|
|
6
|
+
Translations: [English](FAQ.md) · [中文](FAQ.zh.md)
|
|
7
|
+
|
|
8
|
+
## Содержание
|
|
9
|
+
|
|
10
|
+
- [Восстановление секретов после карантина `.corrupt-*`](#восстановление-секретов-после-карантина-corrupt-)
|
|
11
|
+
- [Webhook-триггеры: можно ли переиграть запрос (replay)?](#webhook-триггеры-можно-ли-переиграть-запрос-replay)
|
|
12
|
+
|
|
13
|
+
## Восстановление секретов после карантина `.corrupt-*`
|
|
14
|
+
|
|
15
|
+
Карантин срабатывает, когда `secrets.json` не парсится (обрыв записи,
|
|
16
|
+
ручное редактирование). Файл **не удаляется**, а переименовывается в
|
|
17
|
+
`secrets.json.corrupt-<метка времени>` рядом с оригиналом. Это побочный эффект
|
|
18
|
+
операции чтения — автоматического восстановления нет, чтобы ничто не могло
|
|
19
|
+
затереть данные.
|
|
20
|
+
|
|
21
|
+
Порядок восстановления:
|
|
22
|
+
|
|
23
|
+
1. Найдите файл в каталоге плагина: `%APPDATA%\opencode\windows-scheduler\`
|
|
24
|
+
(Windows) или `~/.config/opencode/windows-scheduler/` (macOS/Linux,
|
|
25
|
+
либо `$XDG_CONFIG_HOME`).
|
|
26
|
+
2. Откройте его в редакторе: обычно это обрезанный JSON. Исправьте синтаксис.
|
|
27
|
+
3. Верните исправленный файл под именем `secrets.json` (копию `.corrupt-*`
|
|
28
|
+
оставьте как бэкап) и проверьте `manage_secrets` (`action: "list"`).
|
|
29
|
+
4. Если файл не восстанавливается — задайте секреты заново
|
|
30
|
+
(`manage_secrets`, `action: "set"`). Значения, зашифрованные утерянным
|
|
31
|
+
`secrets.key`, восстановить нельзя — только повторный ввод.
|
|
32
|
+
5. Редкий случай: rename не удался и запись заблокирована
|
|
33
|
+
(«Запись новых секретов заблокирована»). Уберите битый файл вручную
|
|
34
|
+
(переместите в сторону), затем задайте секреты заново.
|
|
35
|
+
|
|
36
|
+
## Webhook-триггеры: можно ли переиграть запрос (replay)?
|
|
37
|
+
|
|
38
|
+
Да, в обоих оставшихся режимах аутентификации запросы replayable — защита от
|
|
39
|
+
повтора лежит на отправителе:
|
|
40
|
+
|
|
41
|
+
- **Подпись без `timestampToleranceSeconds` (= 0, legacy).** HMAC покрывает
|
|
42
|
+
только тело — перехваченный запрос можно переиграть бесконечно. Задайте
|
|
43
|
+
ненулевой tolerance и шлите `X-Scheduler-Timestamp`: подпись будет покрывать
|
|
44
|
+
`<timestamp>.<body>`, и запрос вне окна перестанет приниматься.
|
|
45
|
+
- **Token-only режим.** Токен тоже replayable — планировщик не отличит повтор
|
|
46
|
+
от атаки. Если перейти на подпись нельзя: храните токен в секретах CI,
|
|
47
|
+
регулярно ротируйте, выдавайте по одному на задачу и делайте задачу
|
|
48
|
+
идемпотентной.
|
|
49
|
+
- **GitHub Actions** сам `X-Scheduler-Timestamp` не присылает, поэтому
|
|
50
|
+
`X-Hub-Signature-256` работает в legacy-режиме. Подписывайте
|
|
51
|
+
`<timestamp>.<body>` отдельным шагом workflow общим секретом.
|
|
52
|
+
- Планировщик не ведёт кэш повторов — дедупликация уникальных запросов на
|
|
53
|
+
стороне отправителя.
|
package/docs/FAQ.zh.md
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# 常见问题
|
|
2
|
+
|
|
3
|
+
常见问题与恢复场景。
|
|
4
|
+
|
|
5
|
+
Translations: [English](FAQ.md) · [Русский](FAQ.ru.md)
|
|
6
|
+
|
|
7
|
+
## 目录
|
|
8
|
+
|
|
9
|
+
- [`.corrupt-*` 隔离后如何恢复密钥](#隔离后如何恢复密钥)
|
|
10
|
+
- [Webhook 触发器:请求会被重放吗?](#webhook-触发器请求会被重放吗)
|
|
11
|
+
|
|
12
|
+
## 隔离后如何恢复密钥
|
|
13
|
+
|
|
14
|
+
当 `secrets.json` 无法解析(写入被中断或手工编辑)时触发隔离。文件**不会被删除**,
|
|
15
|
+
而是重命名为同目录下的 `secrets.json.corrupt-<时间戳>`。这是读取操作的副作用;
|
|
16
|
+
恢复**按设计是手工的**,以免任何自动重写破坏数据。
|
|
17
|
+
|
|
18
|
+
恢复步骤:
|
|
19
|
+
|
|
20
|
+
1. 在插件目录中找到该文件:`%APPDATA%\opencode\windows-scheduler\`(Windows)
|
|
21
|
+
或 `~/.config/opencode/windows-scheduler/`(macOS/Linux,或 `$XDG_CONFIG_HOME`)。
|
|
22
|
+
2. 用编辑器打开:通常是截断的 JSON,修正语法。
|
|
23
|
+
3. 把修好的文件复制回 `secrets.json`(保留 `.corrupt-*` 副本作为备份),
|
|
24
|
+
用 `manage_secrets`(`action: "list"`)验证。
|
|
25
|
+
4. 如果文件无法修复,重新设置密钥(`manage_secrets`,`action: "set"`)。
|
|
26
|
+
用丢失的 `secrets.key` 加密的值无法恢复——请重新输入。
|
|
27
|
+
5. 罕见情况:重命名失败且写入被阻止("Writing new secrets is blocked")。
|
|
28
|
+
手工移走损坏文件,然后重新设置密钥。
|
|
29
|
+
|
|
30
|
+
## Webhook 触发器:请求会被重放吗?
|
|
31
|
+
|
|
32
|
+
会——在两种剩余认证模式下请求都可被重放,因此防重放是发送方的责任:
|
|
33
|
+
|
|
34
|
+
- **带签名但未设置 `timestampToleranceSeconds`(= 0,旧模式)。** HMAC 只覆盖请求体,
|
|
35
|
+
被截获的请求可以永远重放。设置非零容忍窗口并发送 `X-Scheduler-Timestamp`:
|
|
36
|
+
签名随后覆盖 `<timestamp>.<body>`,窗口之外的请求会被拒绝。
|
|
37
|
+
- **仅 Token 模式。** Token 同样可被重放——调度器无法区分重复请求和攻击。
|
|
38
|
+
如果无法切换到签名:把 Token 放在 CI secrets 中,定期轮换,每个任务单独签发,
|
|
39
|
+
并让任务幂等。
|
|
40
|
+
- **GitHub Actions** 自己不发送 `X-Scheduler-Timestamp`,因此
|
|
41
|
+
`X-Hub-Signature-256` 以旧模式运行。可在单独的 workflow 步骤中用共享密钥
|
|
42
|
+
对 `<timestamp>.<body>` 签名。
|
|
43
|
+
- 调度器不保留重放缓存——对唯一请求去重是发送方的责任。
|
package/docs/FEATURES.md
CHANGED
|
@@ -3,12 +3,14 @@
|
|
|
3
3
|
A complete catalog of what the scheduler can do, with examples and the caveats that
|
|
4
4
|
matter in practice.
|
|
5
5
|
|
|
6
|
+
Translations: [中文](FEATURES.zh.md).
|
|
7
|
+
|
|
6
8
|
- [Scheduling](#scheduling)
|
|
7
9
|
- [Execution policy](#execution-policy)
|
|
8
10
|
- [Orchestration](#orchestration)
|
|
9
11
|
- [Multi-repository workspaces](#multi-repository-workspaces)
|
|
10
|
-
- [Profiles (multi-project)](#profiles-multi-project)
|
|
11
|
-
- [Workspace environment variables](#workspace-environment-variables)
|
|
12
|
+
- [Profiles (multi-project)](#profiles-multi-project-sprint-21)
|
|
13
|
+
- [Workspace environment variables](#workspace-environment-variables-sprint-21)
|
|
12
14
|
- [Observability](#observability)
|
|
13
15
|
- [Management](#management)
|
|
14
16
|
- [Agent interface](#agent-interface)
|
|
@@ -102,9 +104,9 @@ it is never accepted from user input or exported as plain text.
|
|
|
102
104
|
- `notBefore` / `notAfter` — daily launch window in `HH:MM` (may cross midnight,
|
|
103
105
|
e.g. `22:00`–`06:00`). A run that fires outside the window is **postponed**
|
|
104
106
|
until the window opens (once, via a defer-file), not skipped.
|
|
105
|
-
- `activeDays` — allowed weekdays `0`=Sunday … `6`=Saturday (
|
|
107
|
+
- `activeDays` — allowed weekdays `0`=Sunday … `6`=Saturday (Sprint 27). Empty or
|
|
106
108
|
all seven means every day. Applies to cron and event triggers.
|
|
107
|
-
- `windowPolicy` — behaviour outside the window or on a disallowed day (
|
|
109
|
+
- `windowPolicy` — behaviour outside the window or on a disallowed day (Sprint 27):
|
|
108
110
|
`postpone` (default) waits for the next opening (max 12 hours), `skip` drops the
|
|
109
111
|
run, `run` executes anyway.
|
|
110
112
|
- `pausedUntil` — pause a task until an ISO moment. `pause_task` accepts
|
|
@@ -125,27 +127,16 @@ it is never accepted from user input or exported as plain text.
|
|
|
125
127
|
The file is watched with chokidar in the plugin host, changes are debounced. File
|
|
126
128
|
triggers ignore `schedule`.
|
|
127
129
|
|
|
128
|
-
#### Glob
|
|
130
|
+
#### Glob masks for file triggers (Sprint 27)
|
|
129
131
|
|
|
130
|
-
`watchGlobs`
|
|
132
|
+
`watchGlobs` and `watchIgnore` restrict which changes count as a trigger:
|
|
131
133
|
|
|
132
|
-
|
|
133
|
-
{
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
"watchPath": "C:\\projects\\site",
|
|
137
|
-
"watchGlobs": ["**/*.md", "**/*.html"],
|
|
138
|
-
"watchIgnore": ["node_modules/**", "**/*.log"],
|
|
139
|
-
"prompt": "Rebuild the static site when docs change."
|
|
140
|
-
}
|
|
141
|
-
```
|
|
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.
|
|
142
138
|
|
|
143
|
-
|
|
144
|
-
`?` (один символ), `[abc]` / `[a-z]` (классы), `{a,b}` (альтернативы) и `!`
|
|
145
|
-
(отрицание). Пустой `watchGlobs` означает «любое изменение». Пути нормализуются
|
|
146
|
-
к POSIX-виду (`\` → `/`), сравнение регистронезависимое на Windows.
|
|
147
|
-
|
|
148
|
-
### Git triggers (Спринт 27)
|
|
139
|
+
### Git triggers (Sprint 27)
|
|
149
140
|
|
|
150
141
|
```json
|
|
151
142
|
{
|
|
@@ -160,16 +151,15 @@ triggers ignore `schedule`.
|
|
|
160
151
|
}
|
|
161
152
|
```
|
|
162
153
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
поддерживает `*` и `?`).
|
|
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 `?`).
|
|
169
159
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
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.
|
|
173
163
|
|
|
174
164
|
### MCP event triggers
|
|
175
165
|
|
|
@@ -251,6 +241,12 @@ the scheduler entry.
|
|
|
251
241
|
|
|
252
242
|
### Tool restrictions
|
|
253
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
|
+
|
|
254
250
|
`allowedTools` and `deniedTools` are enforced for the `opencode run` process that the
|
|
255
251
|
task wrapper starts. The wrapper passes the generated `permissions` rules to the
|
|
256
252
|
process through `OPENCODE_CONFIG_CONTENT`; no file is written to the task workdir, so a
|
|
@@ -339,7 +335,7 @@ Use `workspaceId` instead of `workingDirectory` to run a task in a workspace. Pa
|
|
|
339
335
|
validated on add/update/import, and the dashboard groups tasks and runs by workspace.
|
|
340
336
|
Workspaces are the unit that matrix builds fan out to.
|
|
341
337
|
|
|
342
|
-
## Profiles (multi-project,
|
|
338
|
+
## Profiles (multi-project, Sprint 21)
|
|
343
339
|
|
|
344
340
|
Profiles let you run several independent scheduler installations inside one plugin,
|
|
345
341
|
each with its own SQLite database, settings, logs, wrappers and dashboard port.
|
|
@@ -357,7 +353,7 @@ This is useful for separating projects, clients or environments (e.g. `default`
|
|
|
357
353
|
`set_profile` switches the active profile (restart hint); `create_profile` /
|
|
358
354
|
`delete_profile` manage named profiles (`default` cannot be deleted).
|
|
359
355
|
|
|
360
|
-
### Workspace environment variables (
|
|
356
|
+
### Workspace environment variables (Sprint 21)
|
|
361
357
|
|
|
362
358
|
Each workspace can carry env variables that are injected into every task run in that
|
|
363
359
|
workspace:
|
|
@@ -394,13 +390,19 @@ pre/post-flight results, next chained task, workspace and tool restrictions. Sta
|
|
|
394
390
|
|
|
395
391
|
Per-task counters and totals: runs, successes, errors, tokens, cost. Available through
|
|
396
392
|
`get_history`, the RPC layer and the dashboard header. A 14-day analytics slice —
|
|
397
|
-
|
|
393
|
+
Per-day buckets (UTC), success rate, token-based cost estimate, top tasks by cost,
|
|
398
394
|
matrix and model breakdowns — is available through `get_analytics` /
|
|
399
|
-
`GET /api/analytics` and the dashboard's
|
|
395
|
+
`GET /api/analytics` and the dashboard's **Analytics for the period** block.
|
|
400
396
|
pruned automatically (age and size limits, see Settings) and can be exported as
|
|
401
397
|
CSV/JSON (`GET /api/history/export`), or as OTLP/JSON for OpenTelemetry
|
|
402
398
|
(`GET /api/history/export?format=otlp`).
|
|
403
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
|
+
|
|
404
406
|
### Prometheus
|
|
405
407
|
|
|
406
408
|
`GET /metrics` exposes the Prometheus text format (0.0.4): `opencode_scheduler_info`,
|
|
@@ -433,6 +435,28 @@ token/signature/timestamp), 403 (channel disabled or credentials missing), 404
|
|
|
433
435
|
(unknown task), 413 (body over `maxBodyBytes`). The dashboard still binds to
|
|
434
436
|
localhost only, so external CI needs a tunnel or self-hosted runner.
|
|
435
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
|
+
|
|
436
460
|
### OpenTelemetry
|
|
437
461
|
|
|
438
462
|
History can be exported as OTLP/JSON: one span per run, deterministic 32-hex
|
|
@@ -501,23 +525,31 @@ and native OS notifications — configurable in settings and testable with
|
|
|
501
525
|
- **Quiet hours:** `quietHours.enabled` with `from`/`to` in `HH:MM` (an overnight
|
|
502
526
|
range such as 22:00 → 08:00 is supported). During the window `success` and
|
|
503
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.
|
|
504
535
|
- **Matrix notifications:** on family completion — success, `partial` (`onPartial`)
|
|
505
536
|
and all clones failed (`onAllFailed`). A stuck detector reports clones running
|
|
506
537
|
longer than `matrix.stuckAfterMinutes` (default 60, `0` disables) once per run.
|
|
507
538
|
- **Digest:** `digest.enabled` sends a daily (`frequency: "daily"`, at `digest.time`)
|
|
508
539
|
or weekly (Mondays, catch-up afterwards) summary: runs, success rate, cost, tokens
|
|
509
540
|
and top errors through every enabled channel. Also available as the
|
|
510
|
-
`send_digest` RPC and the GUI's
|
|
541
|
+
`send_digest` RPC and the GUI's **Send digest now** button (manual sends
|
|
511
542
|
do not move the schedule).
|
|
512
543
|
- **Test button:** sends a test message to `all`, `webhook`, `telegram` or `native`
|
|
513
544
|
and reports per-channel success/failure. Failures in one channel never block the
|
|
514
545
|
others and never throw into the task run.
|
|
515
546
|
|
|
516
|
-
### Secrets (
|
|
547
|
+
### Secrets (Sprint 26)
|
|
517
548
|
|
|
518
549
|
Encrypted secret storage in `<PLUGIN_DIR>/secrets.json` with AES-256-GCM and a
|
|
519
|
-
32-byte key file `secrets.key` (
|
|
520
|
-
|
|
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
|
|
521
553
|
`[A-Za-z0-9_.-]` and are up to 64 characters; list shows only name, masked preview
|
|
522
554
|
(`••••` + last 4 chars) and update time — never the value.
|
|
523
555
|
|
|
@@ -527,7 +559,28 @@ name-only warning). Secret references survive masking — they are shown verbati
|
|
|
527
559
|
the GUI env editor — while literal secret-like values (`TOKEN=`, `PASSWORD=`, …)
|
|
528
560
|
are masked as `***` in logs, structured logs, history and audit.
|
|
529
561
|
|
|
530
|
-
|
|
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)
|
|
531
584
|
|
|
532
585
|
Every mutation — task create/update/delete/run, settings, templates, profiles,
|
|
533
586
|
workspaces, secrets, import, history cleanup — is recorded in an `audit_log`
|
|
@@ -535,7 +588,7 @@ table in SQLite with action, target type/target, actor (`mcp`/`gui`/`http`),
|
|
|
535
588
|
source, redacted details and remote address. Indexes on `ts` and `action`;
|
|
536
589
|
retention defaults to 90 days / 10 000 records with automatic cleanup.
|
|
537
590
|
|
|
538
|
-
The `get_audit_log` tool (and the
|
|
591
|
+
The `get_audit_log` tool (and the **Audit log** GUI panel) reads the journal
|
|
539
592
|
with filters by `action`, `target`, `actor`, `since`/`until` and `limit`. Also
|
|
540
593
|
available as RPC `get_audit` and HTTP `GET /api/audit`. Secret values in details
|
|
541
594
|
are redacted; `${secret:NAME}` references are preserved verbatim.
|
|
@@ -552,15 +605,15 @@ Global defaults (timeout, concurrency, notifications, history retention) live in
|
|
|
552
605
|
raw run log bounded: `history.retentionDays` (default 30) and `history.maxRecords`
|
|
553
606
|
(default 5000); `0` disables the respective limit. Cleanup runs at most once a day on
|
|
554
607
|
plugin start, records `lastCleanupAt` / `lastCleanupDeleted`, and is also available as
|
|
555
|
-
the `cleanup_history` RPC and the GUI's
|
|
608
|
+
the `cleanup_history` RPC and the GUI's **Clear now** button. Aggregates in
|
|
556
609
|
`metrics.json` are not affected by retention.
|
|
557
610
|
|
|
558
611
|
## Agent interface
|
|
559
612
|
|
|
560
|
-
Twenty-
|
|
613
|
+
Twenty-five tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
|
|
561
614
|
`run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
|
|
562
615
|
`manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
|
|
563
|
-
`get_analytics`, `manage_settings`, `manage_templates`, `manage_profiles`,
|
|
616
|
+
`get_analytics`, `manage_settings`, `manage_local_ai`, `manage_templates`, `manage_profiles`,
|
|
564
617
|
`transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
|
|
565
618
|
`manage_secrets`, `get_audit_log`,
|
|
566
619
|
`emit_event`.
|
|
@@ -570,6 +623,50 @@ least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
|
|
|
570
623
|
create → dry-run → run-now → inspect loop. It is registered automatically by the
|
|
571
624
|
plugin, no installation step required.
|
|
572
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
|
+
|
|
573
670
|
## Platform support
|
|
574
671
|
|
|
575
672
|
| Capability | Windows | Linux | macOS |
|