agent-steward 0.0.4 → 0.0.6

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.
Files changed (279) hide show
  1. package/CHANGELOG.md +309 -2
  2. package/CROSS_PLATFORM.md +19 -0
  3. package/README.md +55 -8
  4. package/ROADMAP-STRATEGY.md +22 -19
  5. package/ROADMAP.md +230 -159
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +356 -0
  9. package/dist/core/analytics.d.ts +6 -0
  10. package/dist/core/analytics.d.ts.map +1 -1
  11. package/dist/core/analytics.js +20 -3
  12. package/dist/core/audit.d.ts +6 -0
  13. package/dist/core/audit.d.ts.map +1 -1
  14. package/dist/core/audit.js +24 -0
  15. package/dist/core/budget.d.ts +118 -0
  16. package/dist/core/budget.d.ts.map +1 -0
  17. package/dist/core/budget.js +206 -0
  18. package/dist/core/cron-to-schtasks.d.ts.map +1 -1
  19. package/dist/core/cron-to-schtasks.js +38 -0
  20. package/dist/core/dry-run.d.ts +26 -1
  21. package/dist/core/dry-run.d.ts.map +1 -1
  22. package/dist/core/dry-run.js +199 -8
  23. package/dist/core/execution.d.ts +203 -0
  24. package/dist/core/execution.d.ts.map +1 -0
  25. package/dist/core/execution.js +309 -0
  26. package/dist/core/feedback.d.ts +192 -0
  27. package/dist/core/feedback.d.ts.map +1 -0
  28. package/dist/core/feedback.js +426 -0
  29. package/dist/core/gate-integrity.d.ts +71 -0
  30. package/dist/core/gate-integrity.d.ts.map +1 -0
  31. package/dist/core/gate-integrity.js +275 -0
  32. package/dist/core/git-trigger.d.ts.map +1 -1
  33. package/dist/core/git-trigger.js +14 -2
  34. package/dist/core/guard-run.d.ts +4 -0
  35. package/dist/core/guard-run.d.ts.map +1 -0
  36. package/dist/core/guard-run.js +101 -0
  37. package/dist/core/guard.d.ts +52 -0
  38. package/dist/core/guard.d.ts.map +1 -0
  39. package/dist/core/guard.js +362 -0
  40. package/dist/core/local-ai.d.ts.map +1 -1
  41. package/dist/core/local-ai.js +7 -3
  42. package/dist/core/lock.d.ts +41 -0
  43. package/dist/core/lock.d.ts.map +1 -1
  44. package/dist/core/lock.js +141 -29
  45. package/dist/core/matrix.d.ts +8 -0
  46. package/dist/core/matrix.d.ts.map +1 -1
  47. package/dist/core/matrix.js +132 -17
  48. package/dist/core/mission.d.ts +103 -0
  49. package/dist/core/mission.d.ts.map +1 -0
  50. package/dist/core/mission.js +374 -0
  51. package/dist/core/opencode-models.d.ts +2 -2
  52. package/dist/core/opencode-models.d.ts.map +1 -1
  53. package/dist/core/opencode-models.js +28 -21
  54. package/dist/core/opencode-usage.d.ts +35 -0
  55. package/dist/core/opencode-usage.d.ts.map +1 -0
  56. package/dist/core/opencode-usage.js +132 -0
  57. package/dist/core/pipeline-apply.d.ts +38 -0
  58. package/dist/core/pipeline-apply.d.ts.map +1 -0
  59. package/dist/core/pipeline-apply.js +117 -0
  60. package/dist/core/pipeline-io.d.ts +13 -0
  61. package/dist/core/pipeline-io.d.ts.map +1 -0
  62. package/dist/core/pipeline-io.js +78 -0
  63. package/dist/core/pipeline-map.d.ts +52 -0
  64. package/dist/core/pipeline-map.d.ts.map +1 -0
  65. package/dist/core/pipeline-map.js +208 -0
  66. package/dist/core/pipeline-spec.d.ts +109 -0
  67. package/dist/core/pipeline-spec.d.ts.map +1 -0
  68. package/dist/core/pipeline-spec.js +554 -0
  69. package/dist/core/ps-wrapper.d.ts +27 -2
  70. package/dist/core/ps-wrapper.d.ts.map +1 -1
  71. package/dist/core/ps-wrapper.js +424 -65
  72. package/dist/core/record-history.d.ts.map +1 -1
  73. package/dist/core/record-history.js +206 -33
  74. package/dist/core/router/rules.d.ts.map +1 -1
  75. package/dist/core/router/rules.js +6 -0
  76. package/dist/core/run-mode.d.ts +12 -0
  77. package/dist/core/run-mode.d.ts.map +1 -0
  78. package/dist/core/run-mode.js +17 -0
  79. package/dist/core/scheduler/linux.d.ts +8 -1
  80. package/dist/core/scheduler/linux.d.ts.map +1 -1
  81. package/dist/core/scheduler/linux.js +34 -9
  82. package/dist/core/scheduler/logs.d.ts +4 -0
  83. package/dist/core/scheduler/logs.d.ts.map +1 -1
  84. package/dist/core/scheduler/logs.js +25 -1
  85. package/dist/core/scheduler/mac.d.ts +44 -2
  86. package/dist/core/scheduler/mac.d.ts.map +1 -1
  87. package/dist/core/scheduler/mac.js +126 -15
  88. package/dist/core/scheduler/windows.d.ts.map +1 -1
  89. package/dist/core/scheduler/windows.js +15 -12
  90. package/dist/core/secrets.d.ts.map +1 -1
  91. package/dist/core/secrets.js +18 -8
  92. package/dist/core/self-analysis.d.ts +32 -2
  93. package/dist/core/self-analysis.d.ts.map +1 -1
  94. package/dist/core/self-analysis.js +38 -27
  95. package/dist/core/shutdown.d.ts +33 -2
  96. package/dist/core/shutdown.d.ts.map +1 -1
  97. package/dist/core/shutdown.js +58 -2
  98. package/dist/core/structured-log.d.ts +37 -1
  99. package/dist/core/structured-log.d.ts.map +1 -1
  100. package/dist/core/structured-log.js +37 -0
  101. package/dist/core/usage-surface.d.ts +25 -0
  102. package/dist/core/usage-surface.d.ts.map +1 -0
  103. package/dist/core/usage-surface.js +41 -0
  104. package/dist/core/worktree-run.d.ts +4 -0
  105. package/dist/core/worktree-run.d.ts.map +1 -0
  106. package/dist/core/worktree-run.js +164 -0
  107. package/dist/core/worktree.d.ts +115 -0
  108. package/dist/core/worktree.d.ts.map +1 -0
  109. package/dist/core/worktree.js +462 -0
  110. package/dist/core/wrappers/bash.d.ts +19 -0
  111. package/dist/core/wrappers/bash.d.ts.map +1 -1
  112. package/dist/core/wrappers/bash.js +230 -27
  113. package/dist/db/capability-repo.d.ts +43 -2
  114. package/dist/db/capability-repo.d.ts.map +1 -1
  115. package/dist/db/capability-repo.js +96 -11
  116. package/dist/db/history-repo.d.ts +70 -5
  117. package/dist/db/history-repo.d.ts.map +1 -1
  118. package/dist/db/history-repo.js +170 -29
  119. package/dist/db/metrics-repo.d.ts +20 -2
  120. package/dist/db/metrics-repo.d.ts.map +1 -1
  121. package/dist/db/metrics-repo.js +35 -13
  122. package/dist/db/migrate.d.ts.map +1 -1
  123. package/dist/db/migrate.js +37 -17
  124. package/dist/db/recovery.d.ts +3 -1
  125. package/dist/db/recovery.d.ts.map +1 -1
  126. package/dist/db/recovery.js +11 -5
  127. package/dist/db/run-journal.d.ts +33 -5
  128. package/dist/db/run-journal.d.ts.map +1 -1
  129. package/dist/db/run-journal.js +78 -14
  130. package/dist/db/run-resume.d.ts +5 -0
  131. package/dist/db/run-resume.d.ts.map +1 -1
  132. package/dist/db/run-resume.js +9 -2
  133. package/dist/db/runs-repo.d.ts +19 -2
  134. package/dist/db/runs-repo.d.ts.map +1 -1
  135. package/dist/db/runs-repo.js +91 -60
  136. package/dist/db/schema.d.ts +2 -2
  137. package/dist/db/schema.d.ts.map +1 -1
  138. package/dist/db/schema.js +132 -2
  139. package/dist/db/templates-repo.d.ts +2 -2
  140. package/dist/db/templates-repo.d.ts.map +1 -1
  141. package/dist/db/templates-repo.js +5 -3
  142. package/dist/history.d.ts +7 -2
  143. package/dist/history.d.ts.map +1 -1
  144. package/dist/history.js +4 -2
  145. package/dist/hook-output.d.ts +2 -0
  146. package/dist/hook-output.d.ts.map +1 -0
  147. package/dist/hook-output.js +31 -0
  148. package/dist/i18n.d.ts +5 -0
  149. package/dist/i18n.d.ts.map +1 -1
  150. package/dist/i18n.js +11 -4
  151. package/dist/index.d.ts +375 -47
  152. package/dist/index.d.ts.map +1 -1
  153. package/dist/index.js +1344 -192
  154. package/dist/notifications.d.ts +53 -2
  155. package/dist/notifications.d.ts.map +1 -1
  156. package/dist/notifications.js +168 -21
  157. package/dist/profiles.d.ts.map +1 -1
  158. package/dist/profiles.js +82 -10
  159. package/dist/rpc.d.ts +354 -0
  160. package/dist/rpc.d.ts.map +1 -1
  161. package/dist/rpc.js +145 -0
  162. package/dist/server.d.ts +32 -2
  163. package/dist/server.d.ts.map +1 -1
  164. package/dist/server.js +154 -30
  165. package/dist/settings.d.ts +44 -2
  166. package/dist/settings.d.ts.map +1 -1
  167. package/dist/settings.js +85 -3
  168. package/dist/shared/jobs-view.d.ts +1 -1
  169. package/dist/shared/jobs-view.d.ts.map +1 -1
  170. package/dist/shared/jobs-view.js +2 -0
  171. package/dist/task-transfer.d.ts +21 -0
  172. package/dist/task-transfer.d.ts.map +1 -1
  173. package/dist/task-transfer.js +64 -3
  174. package/dist/templates.d.ts +2 -2
  175. package/dist/templates.d.ts.map +1 -1
  176. package/dist/templates.js +3 -3
  177. package/dist/types.d.ts +22 -2
  178. package/dist/types.d.ts.map +1 -1
  179. package/dist/workspaces.d.ts.map +1 -1
  180. package/dist/workspaces.js +34 -11
  181. package/docs/ARCHITECTURE.md +319 -66
  182. package/docs/COMPATIBILITY.md +2 -2
  183. package/docs/CONCEPT.md +18 -4
  184. package/docs/CROSS_PLATFORM.ru.md +20 -0
  185. package/docs/CROSS_PLATFORM.zh.md +18 -0
  186. package/docs/EXECUTION-LOOP.md +28 -10
  187. package/docs/FEATURES.md +129 -7
  188. package/docs/FEATURES.zh.md +97 -6
  189. package/docs/MIGRATION.md +2 -2
  190. package/docs/PIPELINE.md +293 -0
  191. package/docs/QA-A2-GUI-TUI.md +205 -0
  192. package/docs/README.ru.md +43 -4
  193. package/docs/README.zh.md +44 -4
  194. package/docs/SAFETY.md +23 -3
  195. package/gui-experimental.cjs +9 -8
  196. package/locales/en.json +58 -3
  197. package/locales/ru.json +58 -3
  198. package/locales/zh.json +58 -3
  199. package/opencode.pipeline.yaml +35 -0
  200. package/package.json +36 -4
  201. package/scripts/check-eslint-baseline.mjs +139 -0
  202. package/scripts/gen-test-plan-counters.mjs +117 -0
  203. package/scripts/github-ci-fetch.ps1 +37 -0
  204. package/scripts/pl-commit.ps1 +112 -0
  205. package/scripts/qa-a2-commit.ps1 +104 -0
  206. package/scripts/test-home.mjs +107 -0
  207. package/skills/scheduled-job-best-practices/SKILL.md +95 -1
  208. package/skills/scheduled-job-best-practices/references/recipes.md +139 -0
  209. package/src/cli.ts +417 -0
  210. package/src/core/analytics.ts +27 -4
  211. package/src/core/audit.ts +25 -0
  212. package/src/core/budget.ts +340 -0
  213. package/src/core/cron-to-schtasks.ts +42 -0
  214. package/src/core/dry-run.ts +235 -12
  215. package/src/core/execution.ts +538 -0
  216. package/src/core/feedback.ts +582 -0
  217. package/src/core/file-watcher.ts +2 -2
  218. package/src/core/gate-integrity.ts +330 -0
  219. package/src/core/git-trigger.ts +18 -5
  220. package/src/core/guard-run.ts +119 -0
  221. package/src/core/guard.ts +431 -0
  222. package/src/core/local-ai.ts +7 -3
  223. package/src/core/lock.ts +178 -37
  224. package/src/core/matrix.ts +158 -52
  225. package/src/core/mission.ts +531 -0
  226. package/src/core/native-notify.ts +1 -1
  227. package/src/core/opencode-models.ts +30 -21
  228. package/src/core/opencode-usage.ts +182 -0
  229. package/src/core/pipeline-apply.ts +158 -0
  230. package/src/core/pipeline-io.ts +96 -0
  231. package/src/core/pipeline-map.ts +283 -0
  232. package/src/core/pipeline-spec.ts +775 -0
  233. package/src/core/ps-wrapper.ts +435 -66
  234. package/src/core/record-history.ts +258 -81
  235. package/src/core/router/rules.ts +6 -0
  236. package/src/core/run-mode.ts +19 -0
  237. package/src/core/schedule-gate.ts +1 -1
  238. package/src/core/scheduler/at-fallback.ts +1 -1
  239. package/src/core/scheduler/linux.ts +40 -11
  240. package/src/core/scheduler/logs.ts +34 -3
  241. package/src/core/scheduler/mac.ts +174 -14
  242. package/src/core/scheduler/registry.ts +2 -2
  243. package/src/core/scheduler/windows.ts +19 -15
  244. package/src/core/secrets.ts +26 -19
  245. package/src/core/self-analysis.ts +75 -29
  246. package/src/core/shutdown.ts +90 -4
  247. package/src/core/structured-log.ts +89 -5
  248. package/src/core/telegram.ts +2 -2
  249. package/src/core/triage-worker.ts +7 -7
  250. package/src/core/triage.ts +2 -2
  251. package/src/core/usage-surface.ts +70 -0
  252. package/src/core/worktree-run.ts +199 -0
  253. package/src/core/worktree.ts +600 -0
  254. package/src/core/wrappers/bash.ts +248 -26
  255. package/src/db/capability-repo.ts +127 -10
  256. package/src/db/history-repo.ts +281 -40
  257. package/src/db/metrics-repo.ts +40 -13
  258. package/src/db/migrate.ts +57 -32
  259. package/src/db/recovery.ts +12 -5
  260. package/src/db/run-journal.ts +100 -13
  261. package/src/db/run-resume.ts +17 -1
  262. package/src/db/runs-repo.ts +147 -65
  263. package/src/db/schema.ts +134 -2
  264. package/src/db/templates-repo.ts +5 -3
  265. package/src/gui.tsx +438 -18
  266. package/src/history.ts +11 -4
  267. package/src/hook-output.ts +39 -0
  268. package/src/i18n.ts +12 -4
  269. package/src/index.ts +1902 -320
  270. package/src/notifications.ts +227 -47
  271. package/src/profiles.ts +88 -10
  272. package/src/rpc.ts +158 -0
  273. package/src/server.ts +201 -41
  274. package/src/settings.ts +125 -5
  275. package/src/shared/jobs-view.ts +3 -1
  276. package/src/task-transfer.ts +90 -6
  277. package/src/templates.ts +3 -3
  278. package/src/types.ts +23 -2
  279. package/src/workspaces.ts +37 -14
@@ -54,6 +54,13 @@ interface SchedulerBackend {
54
54
  - Обёртка: `run-task.ps1` + персональный `run-<name>.cmd` в `%APPDATA%\opencode\agent-steward\wrapper`. Legacy-каталог `%APPDATA%\opencode\windows-scheduler` переносится при первом запуске.
55
55
  - Логи: `%APPDATA%\opencode\agent-steward\logs\<name>.log`.
56
56
  - cron конвертируется в schtasks (`convertCronToSchTasks`) — поддерживается тот же набор шаблонов.
57
+ - Промпт передаётся в `opencode run` после `--`, поэтому промпт, начинающийся с `-`,
58
+ не может быть принят за флаг. Обёртка отклоняет промпты длиннее 30 000 символов
59
+ до `CreateProcess` (лимит командной строки — 32 767 символов).
60
+ - Сторож таймаута: дерево процессов читается через `Get-CimInstance`; при сбое CIM
61
+ или пустом результате обёртка переходит на `Get-WmiObject`, затем проверяет
62
+ `tasklist`/`Get-Process`. Если данных о дереве нет, срабатывает fail-closed:
63
+ `taskkill /F /T /PID <root>`, чтобы внуки не остались работать.
57
64
 
58
65
  ### Linux
59
66
  - Задачи живут в управляемом блоке `crontab`:
@@ -70,19 +77,32 @@ interface SchedulerBackend {
70
77
  - Полный cron-синтаксис (в отличие от Windows), т.к. crontab понимает его нативно.
71
78
  - Разовый запуск (`once`): `at -t`; если `at` не установлен, плагин ставит отвязанный процесс `sleep && команда` (`pid:<pid>` в реестре). Fallback не переживает перезагрузку — для надёжности установите пакет `at`.
72
79
  - Удаление/пересборка — только своего блока, остальные строки `crontab` не трогаются.
80
+ - Незакрытый блок плагина (маркер начала без конца) — fail-closed: плагин сообщает об ошибке и не перезаписывает crontab, поэтому строки пользователя после маркера не теряются.
73
81
 
74
82
  ### macOS
75
83
  - Задачи — LaunchAgent-плисты `~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`.
76
84
  - Расписание: `StartInterval` для `* * * * *` и `*/N`, `StartCalendarInterval` для `M * * * *`,
77
85
  `M H * * *`, `M H * * D`.
78
86
  - Пауза = `launchctl unload -w`, возобновление = `launchctl load -w`.
87
+ - Установка приостановленной задачи пишет plist, но не вызывает `load -w`
88
+ (он снял бы паузу); `unload -w` оставляет агент выключенным и после входа.
89
+ - Ошибки `launchctl load` не глотаются: ошибка установки/возобновления содержит
90
+ команду, exit code и stderr (например, `Invalid property list` у битого plist).
79
91
  - Обёртка — тот же `.sh`, что и на Linux; пути конфигов:
80
92
  `~/.config/opencode/agent-steward/` (или `$XDG_CONFIG_HOME`).
81
93
 
82
94
  ### Общая POSIX-обёртка (`.sh`)
83
95
  - `cd` в рабочую директорию, `opencode run` с промптом из файла.
96
+ Промпт идёт после `--`, поэтому ведущий `-` не считается опцией.
97
+ - Backstop argv отклоняет `PROMPT_BYTES >= 131072`: `MAX_ARG_STRLEN` в Linux
98
+ включает завершающий NUL, поэтому полезных данных помещается максимум 131 071 байт.
84
99
  - Логи пишутся в файл через `>>` и дублируются метками времени.
85
100
  - Блокировка через атомарный `mkdir` — защита от параллельных запусков.
101
+ - Node, PS и bash пишут владельца lock как `<pid>-<iso>`; старые форматы
102
+ `<iso>|<pid>` (PS) и голый `<pid>` тоже читаются, поэтому живой lock не
103
+ вытесняется другой средой исполнения.
104
+ - При старте плагин читает владельца и из `<task>.lock`, и из `<task>.lock.d/pid`:
105
+ каталог lock вытесняется только если PID мёртв или отсутствует; возраст — fallback.
86
106
  - Таймаут: дочерний процесс + watchdog (`TERM`, затем `KILL`).
87
107
  - Quality Gate: `bash -lc "<команда>"` (аналог `cmd.exe /c` на Windows).
88
108
  - Метрики: `node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"` —
@@ -53,6 +53,12 @@ interface SchedulerBackend {
53
53
  - 包装脚本:`run-task.ps1` 加每个任务专属的 `run-<name>.cmd`,位于 `%APPDATA%\opencode\agent-steward\wrapper`。旧的 `%APPDATA%\opencode\windows-scheduler` 目录会在首次启动时迁移。
54
54
  - 日志:`%APPDATA%\opencode\agent-steward\logs\<name>.log`。
55
55
  - cron 会转换成 schtasks(`convertCronToSchTasks`)——支持与之前相同的模板集合。
56
+ - 提示词在 `--` 之后传给 `opencode run`,因此以 `-` 开头的提示词不会被当成选项。
57
+ 包装脚本会在 `CreateProcess` 之前拒绝超过 30 000 字符的提示词
58
+ (命令行上限为 32 767 字符)。
59
+ - 超时看门狗:通过 `Get-CimInstance` 读取进程树;如果 CIM 失败或为空,则回退到
60
+ `Get-WmiObject`,再检查 `tasklist`/`Get-Process`。如果完全拿不到树数据,则
61
+ 故障关闭并执行 `taskkill /F /T /PID <root>`,避免孙进程继续运行。
56
62
 
57
63
  ### Linux
58
64
  - 任务保存在受管 `crontab` 块中:
@@ -69,19 +75,31 @@ interface SchedulerBackend {
69
75
  - 支持完整 cron 语法(与 Windows 不同),因为 crontab 原生支持。
70
76
  - 一次性任务(`once`):使用 `at -t`;如果未安装 `at`,插件会退回到分离的 `sleep && 命令` 进程(注册表中为 `pid:<pid>`)。回退方案无法在重启后保留,建议安装 `at` 包。
71
77
  - 删除/重建只触及自己的块,`crontab` 的其他行不受影响。
78
+ - 未闭合的插件块(只有开始标记)按 fail-closed 处理:插件报告错误且不重写 crontab,因此标记之后的用户行不会丢失。
72
79
 
73
80
  ### macOS
74
81
  - 任务是 LaunchAgent plist:`~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`。
75
82
  - 调度:`* * * * *` 和 `*/N` 使用 `StartInterval`,`M * * * *`、`M H * * *`、`M H * * D`
76
83
  使用 `StartCalendarInterval`。
77
84
  - 暂停 = `launchctl unload -w`,恢复 = `launchctl load -w`。
85
+ - 安装已暂停的任务只写入 plist,不调用 `load -w`(它会清除暂停);
86
+ `unload -w` 保证代理在下次登录后仍保持禁用。
87
+ - `launchctl load` 的错误不会被吞掉:安装/恢复失败会带上命令、退出码和
88
+ stderr(例如损坏的 plist 返回 `Invalid property list`)。
78
89
  - 包装脚本与 Linux 相同的 `.sh`;配置路径:
79
90
  `~/.config/opencode/agent-steward/`(或 `$XDG_CONFIG_HOME`)。
80
91
 
81
92
  ### 共享 POSIX 包装脚本(`.sh`)
82
93
  - `cd` 到工作目录,用文件中的提示词执行 `opencode run`。
94
+ 提示词位于 `--` 之后,因此开头的 `-` 不会被当作选项。
95
+ - argv 保护会在 `PROMPT_BYTES >= 131072` 时拒绝运行:Linux 的 `MAX_ARG_STRLEN`
96
+ 包含结尾 NUL,因此最多只有 131 071 字节的有效负载。
83
97
  - 日志通过 `>>` 追加,并带时间戳。
84
98
  - 通过原子 `mkdir` 加锁——防止并行运行。
99
+ - Node、PS 和 bash 都将锁持有者写为 `<pid>-<iso>`;旧格式 `<iso>|<pid>`(PS)和
100
+ 裸 `<pid>` 仍可读取,因此运行中的锁不会被另一种运行时误判为过期。
101
+ - 插件启动时同时读取 `<task>.lock` 与 `<task>.lock.d/pid` 的持有者:只有 PID
102
+ 已死亡或缺失时才清理锁目录,年龄仅作为回退条件。
85
103
  - 超时:子进程 + 看门狗(先 `TERM`,再 `KILL`)。
86
104
  - Quality Gate:`bash -lc "<命令>"`(相当于 Windows 上的 `cmd.exe /c`)。
87
105
  - 指标:`node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"`——
@@ -11,12 +11,15 @@
11
11
  - **Роутер не вызывается live.** `routeStep` / `decideCapabilityRoute` отсутствуют в `index.ts` / `record-history.ts`.
12
12
  - **Карта не обучается.** `recordCapabilityOutcome` не вызывается из горячего пути.
13
13
  - **Эскалация не живая.** `escalateAfterGate` есть, но провал гейта идёт в retry/chain.
14
- - **Нет ad-hoc входа.** Любой запуск требует регистрации: `schedule_task` + `run_task_now`; `once` — это `at` / `schtasks ONCE` / launchd. Цепочки/DAG/retry обходят расписание костылём force-маркера.
14
+ - **Нет ad-hoc входа.** Любой запуск требует регистрации: `schedule_task` + `run_task_now`; `once` — это `at` / `schtasks ONCE` / launchd. Цепочки/DAG/retry обходят расписание костылём force-маркера. *(Закрыто в AB-8: `run_mission` / CLI `run` / GUI / RPC.)*
15
+
16
+ Частично построено: контекст запуска (`src/db/run-context.ts`), per-task/per-window
17
+ бюджеты (`src/core/budget.ts`), целостность гейта (`src/core/gate-integrity.ts`),
18
+ worktree-изоляция (`src/core/worktree.ts`, `src/core/worktree-run.ts`).
15
19
 
16
20
  Не построено вовсе: ledger + provenance; класс риска и компиляция политики;
17
- бюджет миссии; целостность гейта, flake-aware, отложенные эффекты; context
18
- compilation, repo-map, инъекция scaffolding; worktree/sandbox, egress-контроль,
19
- approvals-очередь.
21
+ flake-aware повторы и отложенные эффекты; полноценная context compilation
22
+ (repo-map + инъекция scaffolding); egress-контроль и approvals-очередь.
20
23
 
21
24
  Подтверждение:
22
25
 
@@ -119,12 +122,27 @@ CREATE TABLE gate_outcomes (
119
122
 
120
123
  ## 4. Целостность гейта (спринт 39)
121
124
 
122
- - Gate-файлы и команда вне write-scope агента; snapshot фиксируется на старте миссии.
123
- - `gate_hash` и `policy_hash` пишутся в ledger и сверяются перед вердиктом;
124
- расхождение → `fail` + аудит-инцидент.
125
- - Gate-executor отделён от агента; артефакт применяется к защищённому дереву.
126
- - **Гейт всегда hard.** Shadow/canary — только для маршрутов и адаптеров (49).
127
- - **Тест-атака обязательна:** агент правит тесты → гейт обязан провалить.
125
+ **Реализовано (G-1.2):** при создании задачи `src/core/gate-integrity.ts`
126
+ фиксирует snapshot входов гейта — команду/файл хука, prompt и таймаут — с
127
+ SHA-256 в `PLUGIN_DIR/gate-snapshots/`, вне write-scope задачи. Перед запуском
128
+ гейта обе обёртки (Windows и POSIX) вызывают `gate-integrity.js verify`; при
129
+ расхождении хэша, отсутствии или повреждении snapshot гейт не выполняется,
130
+ запуск переходит в `error` с сообщением «snapshot mismatch». Snapshot
131
+ проверяет именно определение гейта, а не исходники репозитория, которые гейт
132
+ тестирует.
133
+
134
+ **Обязательная тест-атака в CI:** `test-execution-hardening.mjs` (Windows) и
135
+ `test-posix-e2e.mjs` (macOS/Linux) подменяют сгенерированный gate-файл/команду
136
+ на `exit 0` после создания snapshot и требуют падения запуска; оба теста уже
137
+ входят в `npm test`/`test:parallel`. Юнит-проверки хэша и CLI — в
138
+ `test-execution-pipeline.mjs`.
139
+
140
+ **Остаётся планом:** отдельный gate-executor, `gate_outcomes` с `gate_hash`,
141
+ `policy_hash`, `prompt_hash` и `prev_hash` в ledger, аудит-инцидент при
142
+ расхождении и перенос gate-файлов под привилегии, отличные от пользовательских.
143
+ Гейт по-прежнему **всегда hard**; shadow/canary — только для маршрутов и
144
+ адаптеров (49). Подмена самих тестов агентом текущей мерой не детектируется —
145
+ защита ограничена целостностью определения гейта.
128
146
 
129
147
  ## 5. Отложенные внешние эффекты
130
148
 
package/docs/FEATURES.md CHANGED
@@ -247,6 +247,16 @@ read/edit/glob/grep/subagent/skill/webfetch/websearch and denies `shell` and `qu
247
247
  allowed everything. Task-level `legacyShell: true` re-enables `shell` under `hybrid` for
248
248
  jobs migrated from older versions; `legacy` is the blunt alternative.
249
249
 
250
+ > **Autonomous tasks and `tool.blocked`:** with the default `hybrid` policy the agent
251
+ > is denied `shell` and `question`, so an unattended task that tries to run `git status`
252
+ > (or ask a clarifying question) will log `tool.blocked` and cannot complete that step.
253
+ > This is intentional — do **not** switch `defaultPolicy` to `legacy` globally just to
254
+ > silence it. Grant the capability to the specific task instead: add `shell`
255
+ > (and/or `question`, if truly needed) to that task's `allowedTools`, use
256
+ > `legacyShell: true` for migrated jobs, or move the command into `beforeScript` /
257
+ > `qualityGate` / `afterScript`, which run with your user privileges and are not subject
258
+ > to agent tool restrictions. `shell` commands inside scripts are the recommended path.
259
+
250
260
  `allowedTools` and `deniedTools` are enforced for the `opencode run` process that the
251
261
  task wrapper starts. The wrapper passes the generated `permissions` rules to the
252
262
  process through `OPENCODE_CONFIG_CONTENT`; no file is written to the task workdir, so a
@@ -259,6 +269,41 @@ not to hooks, Quality Gates or scripts, which still run with your user privilege
259
269
  for the exact action mapping and known limitations (project/system config, nested
260
270
  subagents).
261
271
 
272
+ ### One-off git worktree (W-1)
273
+
274
+ Set `worktree: true` to run every tick in a fresh `git worktree` of
275
+ `workingDirectory` on its own `agent-steward/...` branch. The wrapper creates the
276
+ worktree after the schedule gate and before `opencode`, passes the path to the agent
277
+ through the prompt preamble and `AGENT_STEWARD_WORKTREE`, and fails the run closed
278
+ if creation fails (for example, the directory is not a git repository). Paths and
279
+ branches are unique per run, so matrix clones and parallel missions can write files
280
+ without touching the main checkout or each other — safe fan-out without Docker.
281
+
282
+ Worktrees live under `PLUGIN_DIR/worktrees` with a `.json` sidecar used by cleanup.
283
+ After the run the wrapper removes the worktree and its `agent-steward/...` branch
284
+ even when the task fails (W-2.1). Leftovers from crashes are swept opportunistically
285
+ on the next run: worktrees older than 24 hours are removed, sidecars without a
286
+ checkout are pruned, and a `.cleanup-lock` serialises concurrent sweeps (W-2.2).
287
+ Cleanup only touches paths under the worktree root that have a sidecar and an
288
+ `agent-steward/` branch, so foreign directories and fresh active runs are never
289
+ deleted. A worktree does not isolate network, API or database access, and Quality
290
+ Gates still run with your user privileges.
291
+
292
+ ### Guard conditions (W-3)
293
+
294
+ Set `guards` on a task to require conditions before it runs: an optional shell
295
+ `command` (exit 0 — пройден, non-zero — скип, `timeoutSeconds` 1..3600) and/or
296
+ `semantic` conditions — `filesExist` / `filesMissing` (relative paths, resolved
297
+ inside the worktree or cwd), `branch` (glob), and `changedPaths` (glob, at least
298
+ one path in the diff of `changedSince..HEAD`, default `HEAD~1`). All conditions
299
+ are ANDed: when any check fails or errors, the run is skipped gracefully with a
300
+ visible `skipped` status in history and the GUI (`record-history --skip`, no
301
+ notification and no success/error chain). Guards are evaluated after the
302
+ worktree is created, so they run inside the fresh worktree when combined with
303
+ `worktree: true`; the `guard-run.js` helper lives in `src/core/guard-run.ts` and
304
+ `src/core/guard.ts` provides normalization, evaluation and the exit-code
305
+ convention (4 = skip).
306
+
262
307
  ## Orchestration
263
308
 
264
309
  ### Chains
@@ -323,6 +368,21 @@ Behavior worth knowing:
323
368
  - `matrix_control` with `action: "cleanup"` removes orphaned clones whose parent is
324
369
  gone; the same cleanup also runs at plugin startup.
325
370
 
371
+ ### Pipeline as code
372
+
373
+ A whole DAG can be declared in `opencode.pipeline.yaml` and applied as code:
374
+
375
+ - `version: 1`, a pipeline `name`, optional `defaults` and 1..200 `steps`.
376
+ - Each step has a stable `id`, a `prompt` and an optional `needs` list that becomes
377
+ `dependsOn`.
378
+ - `trigger: cron` (default) needs a `schedule`; `trigger: once` needs `runAt`;
379
+ `trigger: dag` runs only after its `needs` succeed.
380
+ - `matrix.workspaces` fans a step out over workspace names or ids.
381
+ - `agent-steward pipeline validate|apply|export` and the `pipeline_validate`,
382
+ `pipeline_apply`, `pipeline_export` tools cover the lifecycle; apply is idempotent,
383
+ skips unchanged steps and never deletes stale tasks.
384
+ - Full format and limits: [PIPELINE.md](PIPELINE.md).
385
+
326
386
  ## Multi-repository workspaces
327
387
 
328
388
  A workspace is a named directory: id, name, path, optional git remote and color.
@@ -348,7 +408,9 @@ This is useful for separating projects, clients or environments (e.g. `default`
348
408
  in the base directory → `default`. Switching profiles writes the marker and requires
349
409
  an OpenCode restart because plugin directories are resolved at module load time.
350
410
  - Dashboard port per profile: `OPENCODE_SCHEDULER_PORT` env var → port from
351
- `profile.json` → server default (3782, then 4782/5782 fallback).
411
+ `profile.json` → server default (3782, then 4782/5782 fallback). A new profile is
412
+ allocated the first free port from 3783 up, skipping 3782/4782, ports already
413
+ recorded in other profiles' `profile.json`, and `OPENCODE_SCHEDULER_PORT`.
352
414
  - RPC: `get_profiles` lists profiles with dirs, ports and the active flag;
353
415
  `set_profile` switches the active profile (restart hint); `create_profile` /
354
416
  `delete_profile` manage named profiles (`default` cannot be deleted).
@@ -403,6 +465,22 @@ rate of $0.01 / 1k tokens. The KPI is labelled as an estimate and links to
403
465
  [docs/SAVINGS.md](SAVINGS.md) with the full methodology; `report.savings` exposes
404
466
  `savedUsd`, `runs`, `tokens` and a per-task breakdown.
405
467
 
468
+ Daily and weekly **budgets** (Economy v2) are configured through `manage_settings`
469
+ (`budgets: { enabled, dailyUsd, weeklyUsd }`, USD; `0` means no limit) or the
470
+ `get_settings`/`save_settings` RPC methods. Spending is accounted from finished
471
+ history rows in the current UTC day / UTC week (Monday start) using the same
472
+ cost rule as analytics; unfinished runs are ignored. `get_analytics` (and
473
+ `GET /api/analytics`) expose `report.budgets` with `day`/`week` usage
474
+ (`spentUsd`, `runs`, `limitUsd`, `remainingUsd`, `ratio`, `exceeded`, `disabled`)
475
+ and a combined `exceeded` flag. When a limit is enabled and reached, new runs
476
+ are paused automatically: `run_task`, `run_mission`, `run_task_now` and the
477
+ RPC/GUI, file-trigger and MCP entry points all refuse to start until the next
478
+ period, with a human-readable reason. An alert is sent to the configured
479
+ notification channels (webhook/Telegram/native) when a run is blocked; repeated
480
+ alerts with the same reason are suppressed for 24 hours. Budgets are fail-open:
481
+ disabled groups and zero limits never block a run, and accounting stays visible
482
+ regardless.
483
+
406
484
  ### Prometheus
407
485
 
408
486
  `GET /metrics` exposes the Prometheus text format (0.0.4): `opencode_scheduler_info`,
@@ -474,6 +552,12 @@ agent's stdout/stderr. `get_task_logs` returns the tail (1–1000 lines).
474
552
  `dry_run` simulates one task or every task: execution order, DAG prerequisites, matrix
475
553
  fan-out and estimated time. Nothing is executed and nothing is created.
476
554
 
555
+ The ad-hoc mission API (`runMission` / `agent-steward run --dry-run`) has its own
556
+ `dryRun` contract: it builds the step plan and its description, but does not acquire
557
+ the `activeWorkspaces` lock and does not write `runs`/`run_steps` to the ledger.
558
+ This is intentional — several dry runs in the same `cwd` run in parallel and leave
559
+ no trace in history. Only a real mission is locked to one workspace at a time.
560
+
477
561
  ### Dashboard
478
562
 
479
563
  A local web dashboard shows tasks, matrix tabs, per-workspace summaries, DAG markers,
@@ -610,14 +694,15 @@ the `cleanup_history` RPC and the GUI's **Clear now** button. Aggregates in
610
694
 
611
695
  ## Agent interface
612
696
 
613
- Twenty-six tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
697
+ Thirty tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
614
698
  `run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
615
699
  `manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
616
700
  `get_analytics`, `self_analysis` (health score, anomalies, trends), `manage_settings`,
617
701
  `manage_local_ai`, `manage_templates`, `manage_profiles`,
618
- `transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
702
+ `transfer_tasks`, `send_notification`, `report_bug`, `get_dashboard_info`, `cleanup_history`,
619
703
  `manage_secrets`, `get_audit_log`,
620
- `emit_event`.
704
+ `emit_event`,
705
+ `pipeline_validate`, `pipeline_apply`, `pipeline_export`.
621
706
 
622
707
  A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
623
708
  least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
@@ -627,6 +712,39 @@ plugin, no installation step required.
627
712
  The `manage_local_ai` tool reads, updates and tests the local triage settings
628
713
  (`action: "get" | "update" | "test"`); see [LOCAL-AI.md](LOCAL-AI.md).
629
714
 
715
+ ## Author feedback (bug reports)
716
+
717
+ `report_bug` sends a structured report to the plugin author through a **write-only**
718
+ receiver (a Cloudflare Worker that creates a GitHub Issue in `DeadSno/agent-steward`).
719
+ The npm package contains **no tokens**: the fine-grained PAT (`issues: write` only)
720
+ lives in the receiver secrets. See [infra/feedback-worker/README.md](../infra/feedback-worker/README.md)
721
+ for deployment.
722
+
723
+ Arguments: `description` (required), `destination: "author" | "local" | "both"`
724
+ (default `author`), `dryRun` (preview only, no network), `includeLogs` (default
725
+ **false**), `includeAnalytics` (default true), `contactEmail`, `taskName`, `channel`.
726
+
727
+ What is sent in the payload (`schemaVersion: 1`): plugin/OS/Node versions,
728
+ locale, active profile, optional task name, the description, and — only when
729
+ explicitly allowed — redacted logs and aggregate metrics. What is **not** sent by
730
+ default: logs, emails, raw environment variables. Client-side redaction removes
731
+ `sk-`/`ghp_`/`xox*`/bot tokens, all values stored via `manage_secrets`, the home
732
+ directory (replaced with `~`) and email addresses (replaced with `[EMAIL]`).
733
+ `contactEmail` is included only if the user provided it explicitly.
734
+
735
+ Privacy controls: `feedback.enabled` defaults to **false**; `includeLogs` defaults
736
+ to **false**; the endpoint must be HTTPS (HTTP only for localhost) and is validated
737
+ on save. Use `report_bug` with `dryRun: true` to inspect the exact payload before
738
+ sending — the plugin displays `schemaVersion`, `reportId`, OS, locale, profile,
739
+ description, contact email, logs and metrics (F-3.1). The GUI has a dedicated
740
+ **Author feedback** settings section. Messages are localized to ru/en/zh.
741
+
742
+ Delivery is fail-open (F-1.6): if the receiver is unavailable, the report is saved
743
+ to the local `feedback_outbox` table and retried on plugin start (max 5 attempts);
744
+ it never blocks task execution. A hash of the description, a 5-minute window and
745
+ an hourly limit (default 6) prevent spam; only hashes, never report text, are stored
746
+ in `feedback_spam`.
747
+
630
748
  ## Local assistant (triage)
631
749
 
632
750
  An optional offline model classifies failed and partial runs (category, severity,
@@ -654,7 +772,9 @@ It never changes run status, retries, Quality Gates, DAG dependencies or history
654
772
  messages are converted to normalized bag-of-words vectors stored in SQLite,
655
773
  compared by cosine similarity against the window, and suppressed above
656
774
  `threshold` (0.85 default). Important statuses are never suppressed. No new
657
- dependencies and no external embedding model are required.
775
+ dependencies and no external embedding model are required. CJK text (Chinese,
776
+ Japanese, Korean) is tokenized into overlapping bigrams, so messages without
777
+ spaces produce non-zero vectors and participate in dedup too.
658
778
  - `notifications.summary` renders at most three short lines for Telegram and
659
779
  toasts. The model returns strict JSON `{"lines": [...]}`; any failure falls
660
780
  back to deterministic truncation (status, error, runtime/tokens/cost), and
@@ -689,8 +809,10 @@ and troubleshooting (including `OLLAMA_CONTEXT_LENGTH`) are documented in
689
809
  not supported.
690
810
  - **No sandbox.** Hooks, Quality Gates and prompts run with your user privileges.
691
811
  - **No authentication on the dashboard.** Localhost only by design.
692
- - **Secrets are not encrypted.** Use environment variables or an external secret
693
- manager.
812
+ - **Secrets are encrypted at rest with AES-256-GCM** in `<PLUGIN_DIR>/secrets.json`
813
+ (see the Secrets section). The key lives in `secrets.key`; losing it makes stored
814
+ values unrecoverable. For higher-sensitivity values, prefer environment variables
815
+ or an external secret manager.
694
816
  - **`allowedTools` / `deniedTools` restrict the agent process, not the whole job.**
695
817
  Hooks, Quality Gates and wrapper scripts still run with your user privileges, and a
696
818
  project-level or system `opencode.jsonc` can weaken task-scoped denies. See the
@@ -210,6 +210,14 @@ read/edit/glob/grep/subagent/skill/webfetch/websearch 并拒绝 `shell` 和 `que
210
210
  `legacyShell: true` 会在 `hybrid` 下为从旧版本迁移来的作业重新启用 `shell`;
211
211
  `legacy` 是粗放的替代方案。
212
212
 
213
+ > **自治任务与 `tool.blocked`:** 默认的 `hybrid` 策略会拒绝 agent 使用 `shell`
214
+ > 和 `question`,因此无人值守任务若尝试运行 `git status`(或询问澄清问题),
215
+ > 会在日志中留下 `tool.blocked` 且无法完成该步骤。这是有意设计——不要仅为消除
216
+ > 它而全局把 `defaultPolicy` 改成 `legacy`。应当为该具体任务授予能力:把 `shell`
217
+ > (确有需要时也包括 `question`)加入该任务的 `allowedTools`,为迁移作业使用
218
+ > `legacyShell: true`,或把命令移入 `beforeScript` / `qualityGate` / `afterScript`
219
+ > ——它们以你的用户权限运行,不受 agent 工具限制约束。推荐在脚本中执行 shell 命令。
220
+
213
221
  `allowedTools` 和 `deniedTools` 对任务包装器启动的 `opencode run` 进程
214
222
  强制生效。包装器通过 `OPENCODE_CONFIG_CONTENT` 把生成的 `permissions` 规则
215
223
  传给该进程;不会向任务工作目录写入任何文件,因此项目级
@@ -221,6 +229,36 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
221
229
  嵌套子代理)见
222
230
  [ARCHITECTURE.md](ARCHITECTURE.md#permission-enforcement--known-limitations-spike-291-findings)。
223
231
 
232
+ ### 一次性 git worktree(W-1)
233
+
234
+ 设置 `worktree: true` 后,每次运行都会在 `workingDirectory` 的全新 `git worktree`
235
+ 中执行,并使用独立的 `agent-steward/...` 分支。包装脚本在调度门禁之后、启动
236
+ `opencode` 之前创建 worktree,通过提示词前导和 `AGENT_STEWARD_WORKTREE` 把路径传给
237
+ Agent;创建失败时(例如目录不是 git 仓库)运行会 fail-closed 终止。每次运行的路径和
238
+ 分支都唯一,因此矩阵克隆和并行任务可以各自写文件,互不影响主工作区和彼此——无需
239
+ Docker 即可安全扇出。
240
+
241
+ Worktree 位于 `PLUGIN_DIR/worktrees`,旁边的 `.json` sidecar 用于清理。运行结束后,
242
+ 包装脚本会删除 worktree 及其 `agent-steward/...` 分支,任务失败时也会删除(W-2.1)。
243
+ 崩溃留下的残留会在下一次运行时顺带清扫:超过 24 小时的 worktree 被删除,没有工作
244
+ 副本的 sidecar 被清理,`.cleanup-lock` 串行化并发清扫(W-2.2)。清理只处理 worktree
245
+ 根目录下带 sidecar 且分支为 `agent-steward/` 的路径,因此不会删除外来目录和正在
246
+ 运行的 worktree。worktree 不隔离网络、API 或数据库访问,Quality Gate 仍以你的
247
+ 用户权限运行。
248
+
249
+ ### Guard 条件(W-3)
250
+
251
+ 可以为任务设置 `guards` — 运行前必须满足的条件:可选的 shell `command`
252
+ (exit 0 表示通过,非 0 表示跳过,`timeoutSeconds` 1..3600)和/或 `semantic`
253
+ 条件 — `filesExist` / `filesMissing`(相对路径,在 worktree 或 cwd 内解析)、
254
+ `branch`(glob)和 `changedPaths`(glob;`changedSince..HEAD` 的 diff 中至少
255
+ 匹配一个路径,默认 `HEAD~1`)。所有条件按「与」组合:任一检查失败或出错时,
256
+ 运行会被优雅跳过,并在历史记录和 GUI 中显示为可见的 `skipped` 状态
257
+ (`record-history --skip`;不发送通知、不触发成功/错误链)。检查在创建
258
+ worktree 之后执行,因此与 `worktree: true` 组合时它们在新 worktree 内运行;
259
+ `guard-run.js` 帮助程序位于 `src/core/guard-run.ts`,`src/core/guard.ts`
260
+ 提供规范化、求值和退出码约定(4 = 跳过)。
261
+
224
262
  ## 编排
225
263
 
226
264
  ### 链式调度
@@ -283,6 +321,20 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
283
321
  - `matrix_control` 的 `action: "cleanup"` 会移除父任务已不存在的孤立
284
322
  克隆;同样的清理也会在插件启动时运行。
285
323
 
324
+ ### 流水线即代码
325
+
326
+ 整个 DAG 可以声明在 `opencode.pipeline.yaml` 中并按代码应用:
327
+
328
+ - `version: 1`、流水线 `name`、可选的 `defaults` 和 1..200 个 `steps`。
329
+ - 每个步骤有稳定的 `id`、`prompt` 和可选的 `needs`(转换为 `dependsOn`)。
330
+ - `trigger: cron`(默认)需要 `schedule`;`trigger: once` 需要 `runAt`;
331
+ `trigger: dag` 只在其 `needs` 成功后运行。
332
+ - `matrix.workspaces` 按 workspace 名称或 id 将步骤扇出。
333
+ - `agent-steward pipeline validate|apply|export` 与 `pipeline_validate`、
334
+ `pipeline_apply`、`pipeline_export` 工具覆盖整个生命周期;apply 幂等、
335
+ 跳过未变化的步骤,且从不删除 stale 任务。
336
+ - 完整格式与限制:[PIPELINE.md](PIPELINE.md)。
337
+
286
338
  ## 多仓库工作区
287
339
 
288
340
  工作区是一个命名目录:id、name、path、可选的 git 远程仓库和颜色。
@@ -308,7 +360,9 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
308
360
  `active-profile` 文件 → `default`。切换配置档案会写入标记文件,并且需要
309
361
  重启 OpenCode,因为插件目录在模块加载时解析。
310
362
  - 每个配置档案的仪表板端口:`OPENCODE_SCHEDULER_PORT` 环境变量 → 来自
311
- `profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782 回退)。
363
+ `profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782 回退)。新配置档案
364
+ 会分配 3783 起的第一个空闲端口,跳过 3782/4782、其他配置档案 `profile.json`
365
+ 中已记录的端口以及 `OPENCODE_SCHEDULER_PORT`。
312
366
  - RPC:`get_profiles` 列出配置档案及其目录、端口和活动标志;
313
367
  `set_profile` 切换活动配置档案(会提示重启);`create_profile` /
314
368
  `delete_profile` 管理命名配置档案(`default` 不能被删除)。
@@ -362,6 +416,19 @@ OTLP/JSON(`GET /api/history/export?format=otlp`)。
362
416
  [docs/SAVINGS.md](SAVINGS.md) 的完整方法说明;`report.savings` 暴露
363
417
  `savedUsd`、`runs`、`tokens` 以及按任务的细分。
364
418
 
419
+ 每日/每周 **预算**(Economy v2)通过 `manage_settings`
420
+ (`budgets: { enabled, dailyUsd, weeklyUsd }`,单位 USD;`0` 表示无限制)
421
+ 或 `get_settings`/`save_settings` RPC 方法配置。支出按当前 UTC 日 /
422
+ UTC 周(周一开始)从已完成的历史记录中统计,使用与分析相同的成本规则;
423
+ 未完成的运行会被忽略。`get_analytics`(以及 `GET /api/analytics`)在
424
+ `report.budgets` 中提供 `day`/`week` 用量(`spentUsd`、`runs`、`limitUsd`、
425
+ `remainingUsd`、`ratio`、`exceeded`、`disabled`)以及总的 `exceeded` 标志。
426
+ 当启用某个限额并达到时,新运行会自动暂停:`run_task`、`run_mission`、
427
+ `run_task_now` 以及 RPC/GUI、文件触发和 MCP 入口都会拒绝启动,并给出原因,
428
+ 直到下一个周期。运行被阻止时会向已配置的通知渠道(webhook/Telegram/原生通知)
429
+ 发送警报;相同原因的重复警报在 24 小时内会被抑制。预算默认 fail-open:
430
+ 禁用的分组和零限制永远不会阻止运行,且统计始终可见。
431
+
365
432
  ### Prometheus
366
433
 
367
434
  `GET /metrics` 暴露 Prometheus 文本格式(0.0.4):`opencode_scheduler_info`、
@@ -566,14 +633,14 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
566
633
 
567
634
  ## Agent 接口
568
635
 
569
- 二十六个工具:`schedule_task`、`list_tasks`、`update_task`、`delete_task`、
636
+ 二十九个工具:`schedule_task`、`list_tasks`、`update_task`、`delete_task`、
570
637
  `run_task_now`、`pause_task`、`resume_task`、`get_history`、`get_task_logs`、`dry_run`、
571
638
  `manage_workspaces`、`matrix_control`(results/cancel/cleanup/preview)、`get_metrics`、
572
639
  `get_analytics`、`self_analysis`(健康评分、异常、趋势)、`manage_settings`、
573
640
  `manage_local_ai`、`manage_templates`、`manage_profiles`、
574
641
  `transfer_tasks`、`send_notification`、`get_dashboard_info`、`cleanup_history`、
575
642
  `manage_secrets`、`get_audit_log`、
576
- `emit_event`。
643
+ `emit_event`、`pipeline_validate`、`pipeline_apply`、`pipeline_export`。
577
644
 
578
645
  捆绑的 skill `scheduled-job-best-practices` 教会 agent 安全的默认做法:
579
646
  最小权限、Quality Gate、超时、矩阵并发、DAG 规则以及
@@ -583,6 +650,27 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
583
650
  `manage_local_ai` 工具读取、更新并测试本地分诊设置
584
651
  (`action: "get" | "update" | "test"`);见 [LOCAL-AI.md](LOCAL-AI.md)。
585
652
 
653
+ ## 作者反馈(bug 报告)
654
+
655
+ `report_bug` 通过**只写**接收端(Cloudflare Worker,在 `DeadSno/agent-steward`
656
+ 创建 GitHub Issue)把结构化报告发送给插件作者;npm 包里不含任何 token,
657
+ fine-grained PAT(仅 `issues:write`)保存在 Worker 的 secrets 中。
658
+
659
+ 参数:`description`(必填)、`destination: "author" | "local" | "both"`
660
+ (默认 `author`)、`dryRun`(只展示 payload,不发网络请求)、
661
+ `includeLogs`(默认 **false**)、`includeAnalytics`、`contactEmail`、`taskName`。
662
+
663
+ 默认发送的 payload(`schemaVersion: 1`)包含插件/操作系统/Node 版本、locale、
664
+ 当前 profile、可选任务名、描述,以及明确允许时才附上的脱敏日志和汇总指标。
665
+ 默认**不**发送日志、邮箱或原始环境变量;客户端会剔除 `sk-`/`ghp_`/`xox*`/bot
666
+ token、`manage_secrets` 中的值、home → `~`、email → `[EMAIL]`。
667
+
668
+ 隐私控制:`feedback.enabled` 默认 **false**,`includeLogs` 默认 **false**;
669
+ endpoint 必须是 https(localhost 可用 http),保存时校验。先调用
670
+ `report_bug` 且 `dryRun: true` 可查看完整 payload,确认后再发送。GUI 中有
671
+ 专门的「作者反馈」设置区,消息提供 ru/en/zh 三种语言。投递采用 fail-open:
672
+ 接收端不可用时报告写入本地 outbox,启动时重试(最多 5 次),不阻塞任务。
673
+
586
674
  ## 本地助手(分诊)
587
675
 
588
676
  一个可选的离线模型对失败和 partial 的运行进行分类(类别、严重程度、
@@ -611,7 +699,9 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
611
699
  在窗口内按余弦相似度比较,超过
612
700
  `threshold`(默认 0.85)时被抑制。重要状态
613
701
  永远不会被抑制。不需要新依赖,也不需要外部
614
- 嵌入模型。
702
+ 嵌入模型。CJK 文本(中文、日文、韩文)按重叠的
703
+ 二元组切分,因此没有空格的消息也会得到非零向量
704
+ 并参与去重。
615
705
  - `notifications.summary` 为 Telegram 和
616
706
  toast 最多渲染三行短文本。模型返回严格的 JSON
617
707
  `{"lines": [...]}`;任何失败都会回退到确定性截断(状态、
@@ -646,8 +736,9 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
646
736
  和 `last` 覆盖常见场景;不支持按消息分叉/分支会话。
647
737
  - **没有沙箱。** 钩子、Quality Gate 和 prompt 都以你的用户权限运行。
648
738
  - **仪表板没有认证。** 设计上仅限 localhost。
649
- - **密钥不加密。** 请使用环境变量或外部密钥
650
- 管理器。
739
+ - **密钥在静态存储时使用 AES-256-GCM 加密**,保存在 `<PLUGIN_DIR>/secrets.json`
740
+ (见 Secrets 一节)。密钥存放在 `secrets.key` 中;丢失后已存储的值无法恢复。
741
+ 对于更高敏感度的密钥,建议使用环境变量或外部密钥管理器。
651
742
  - **`allowedTools` / `deniedTools` 限制的是 agent 进程,而不是整个作业。**
652
743
  钩子、Quality Gate 和包装器脚本仍以你的用户权限运行,而且项目级
653
744
  或系统级 `opencode.jsonc` 可以削弱任务范围的拒绝规则。见
package/docs/MIGRATION.md CHANGED
@@ -27,8 +27,8 @@ timers, launchd, Windows Task Scheduler, or another scheduler plugin.
27
27
  automatically; on V1 restart it). If OpenCode's built-in
28
28
  schedules are enabled, disable them so two schedulers do not run the same work.
29
29
 
30
- 2. **Check Node.** `node --version` must be 20 or newer (22.5+ for the built-in SQLite
31
- driver; Node 24 recommended).
30
+ 2. **Check Node.** `node --version` must be 22.22+ (the built-in SQLite driver and
31
+ chokidar 6 require 22.22+; Node 24 recommended).
32
32
 
33
33
  3. **Inventory the old jobs.** For each job write down: name, schedule, command,
34
34
  working directory, environment variables, timeout, and what "success" means. The