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.
Files changed (333) hide show
  1. package/CHANGELOG.md +376 -0
  2. package/CROSS_PLATFORM.md +149 -0
  3. package/README.md +306 -15
  4. package/ROADMAP-STRATEGY.md +147 -0
  5. package/ROADMAP.md +1069 -0
  6. package/dist/core/analytics.d.ts +132 -0
  7. package/dist/core/analytics.d.ts.map +1 -0
  8. package/dist/core/analytics.js +290 -0
  9. package/dist/core/audit.d.ts +96 -0
  10. package/dist/core/audit.d.ts.map +1 -0
  11. package/dist/core/audit.js +297 -0
  12. package/dist/core/cron-to-schtasks.d.ts +20 -0
  13. package/dist/core/cron-to-schtasks.d.ts.map +1 -0
  14. package/dist/core/cron-to-schtasks.js +250 -0
  15. package/dist/core/dry-run.d.ts +102 -0
  16. package/dist/core/dry-run.d.ts.map +1 -0
  17. package/dist/core/dry-run.js +447 -0
  18. package/dist/core/file-watcher.d.ts +31 -0
  19. package/dist/core/file-watcher.d.ts.map +1 -0
  20. package/dist/core/file-watcher.js +186 -0
  21. package/dist/core/git-trigger.d.ts +82 -0
  22. package/dist/core/git-trigger.d.ts.map +1 -0
  23. package/dist/core/git-trigger.js +312 -0
  24. package/dist/core/glob.d.ts +38 -0
  25. package/dist/core/glob.d.ts.map +1 -0
  26. package/dist/core/glob.js +233 -0
  27. package/dist/core/local-ai.d.ts +52 -0
  28. package/dist/core/local-ai.d.ts.map +1 -0
  29. package/dist/core/local-ai.js +119 -0
  30. package/dist/core/lock.d.ts +57 -0
  31. package/dist/core/lock.d.ts.map +1 -0
  32. package/dist/core/lock.js +195 -0
  33. package/dist/core/matrix.d.ts +167 -0
  34. package/dist/core/matrix.d.ts.map +1 -0
  35. package/dist/core/matrix.js +724 -0
  36. package/dist/core/native-notify.d.ts +36 -0
  37. package/dist/core/native-notify.d.ts.map +1 -0
  38. package/dist/core/native-notify.js +113 -0
  39. package/dist/core/one-shot.d.ts +68 -0
  40. package/dist/core/one-shot.d.ts.map +1 -0
  41. package/dist/core/one-shot.js +139 -0
  42. package/dist/core/otel.d.ts +4 -0
  43. package/dist/core/otel.d.ts.map +1 -0
  44. package/dist/core/otel.js +98 -0
  45. package/dist/core/permissions.d.ts +69 -0
  46. package/dist/core/permissions.d.ts.map +1 -0
  47. package/dist/core/permissions.js +143 -0
  48. package/dist/core/prometheus.d.ts +23 -0
  49. package/dist/core/prometheus.d.ts.map +1 -0
  50. package/dist/core/prometheus.js +146 -0
  51. package/dist/core/ps-wrapper.d.ts +73 -0
  52. package/dist/core/ps-wrapper.d.ts.map +1 -0
  53. package/dist/core/ps-wrapper.js +1071 -0
  54. package/dist/core/record-history.d.ts +25 -0
  55. package/dist/core/record-history.d.ts.map +1 -0
  56. package/dist/core/record-history.js +471 -0
  57. package/dist/core/retention.d.ts +29 -0
  58. package/dist/core/retention.d.ts.map +1 -0
  59. package/dist/core/retention.js +98 -0
  60. package/dist/core/savings.d.ts +70 -0
  61. package/dist/core/savings.d.ts.map +1 -0
  62. package/dist/core/savings.js +87 -0
  63. package/dist/core/schedule-gate.d.ts +2 -0
  64. package/dist/core/schedule-gate.d.ts.map +1 -0
  65. package/dist/core/schedule-gate.js +211 -0
  66. package/dist/core/schedule-v2.d.ts +116 -0
  67. package/dist/core/schedule-v2.d.ts.map +1 -0
  68. package/dist/core/schedule-v2.js +586 -0
  69. package/dist/core/scheduler/index.d.ts +32 -0
  70. package/dist/core/scheduler/index.d.ts.map +1 -0
  71. package/dist/core/scheduler/index.js +63 -0
  72. package/dist/core/scheduler/linux.d.ts +44 -0
  73. package/dist/core/scheduler/linux.d.ts.map +1 -0
  74. package/dist/core/scheduler/linux.js +225 -0
  75. package/dist/core/scheduler/logs.d.ts +11 -0
  76. package/dist/core/scheduler/logs.d.ts.map +1 -0
  77. package/dist/core/scheduler/logs.js +34 -0
  78. package/dist/core/scheduler/mac.d.ts +40 -0
  79. package/dist/core/scheduler/mac.d.ts.map +1 -0
  80. package/dist/core/scheduler/mac.js +207 -0
  81. package/dist/core/scheduler/posix.d.ts +40 -0
  82. package/dist/core/scheduler/posix.d.ts.map +1 -0
  83. package/dist/core/scheduler/posix.js +89 -0
  84. package/dist/core/scheduler/registry.d.ts +41 -0
  85. package/dist/core/scheduler/registry.d.ts.map +1 -0
  86. package/dist/core/scheduler/registry.js +57 -0
  87. package/dist/core/scheduler/types.d.ts +86 -0
  88. package/dist/core/scheduler/types.d.ts.map +1 -0
  89. package/dist/core/scheduler/types.js +1 -0
  90. package/dist/core/scheduler/windows.d.ts +99 -0
  91. package/dist/core/scheduler/windows.d.ts.map +1 -0
  92. package/dist/core/scheduler/windows.js +596 -0
  93. package/dist/core/secrets.d.ts +66 -0
  94. package/dist/core/secrets.d.ts.map +1 -0
  95. package/dist/core/secrets.js +433 -0
  96. package/dist/core/self-analysis.d.ts +117 -0
  97. package/dist/core/self-analysis.d.ts.map +1 -0
  98. package/dist/core/self-analysis.js +539 -0
  99. package/dist/core/self-analysis.test.d.ts +2 -0
  100. package/dist/core/self-analysis.test.d.ts.map +1 -0
  101. package/dist/core/self-analysis.test.js +219 -0
  102. package/dist/core/session.d.ts +42 -0
  103. package/dist/core/session.d.ts.map +1 -0
  104. package/dist/core/session.js +134 -0
  105. package/dist/core/shutdown.d.ts +26 -0
  106. package/dist/core/shutdown.d.ts.map +1 -0
  107. package/dist/core/shutdown.js +49 -0
  108. package/dist/core/structured-log.d.ts +84 -0
  109. package/dist/core/structured-log.d.ts.map +1 -0
  110. package/dist/core/structured-log.js +146 -0
  111. package/dist/core/summary.d.ts +69 -0
  112. package/dist/core/summary.d.ts.map +1 -0
  113. package/dist/core/summary.js +250 -0
  114. package/dist/core/telegram.d.ts +55 -0
  115. package/dist/core/telegram.d.ts.map +1 -0
  116. package/dist/core/telegram.js +344 -0
  117. package/dist/core/triage-chain.d.ts +40 -0
  118. package/dist/core/triage-chain.d.ts.map +1 -0
  119. package/dist/core/triage-chain.js +80 -0
  120. package/dist/core/triage-compare.d.ts +68 -0
  121. package/dist/core/triage-compare.d.ts.map +1 -0
  122. package/dist/core/triage-compare.js +184 -0
  123. package/dist/core/triage-rules.d.ts +23 -0
  124. package/dist/core/triage-rules.d.ts.map +1 -0
  125. package/dist/core/triage-rules.js +196 -0
  126. package/dist/core/triage-shadow.d.ts +91 -0
  127. package/dist/core/triage-shadow.d.ts.map +1 -0
  128. package/dist/core/triage-shadow.js +160 -0
  129. package/dist/core/triage-worker.d.ts +55 -0
  130. package/dist/core/triage-worker.d.ts.map +1 -0
  131. package/dist/core/triage-worker.js +314 -0
  132. package/dist/core/triage.d.ts +76 -0
  133. package/dist/core/triage.d.ts.map +1 -0
  134. package/dist/core/triage.js +271 -0
  135. package/dist/core/watch-paths.d.ts +6 -0
  136. package/dist/core/watch-paths.d.ts.map +1 -0
  137. package/dist/core/watch-paths.js +62 -0
  138. package/dist/core/wrappers/bash.d.ts +95 -0
  139. package/dist/core/wrappers/bash.d.ts.map +1 -0
  140. package/dist/core/wrappers/bash.js +413 -0
  141. package/dist/db/git-state-repo.d.ts +16 -0
  142. package/dist/db/git-state-repo.d.ts.map +1 -0
  143. package/dist/db/git-state-repo.js +38 -0
  144. package/dist/db/history-repo.d.ts +110 -0
  145. package/dist/db/history-repo.d.ts.map +1 -0
  146. package/dist/db/history-repo.js +300 -0
  147. package/dist/db/index.d.ts +47 -0
  148. package/dist/db/index.d.ts.map +1 -0
  149. package/dist/db/index.js +120 -0
  150. package/dist/db/metrics-repo.d.ts +46 -0
  151. package/dist/db/metrics-repo.d.ts.map +1 -0
  152. package/dist/db/metrics-repo.js +103 -0
  153. package/dist/db/migrate.d.ts +24 -0
  154. package/dist/db/migrate.d.ts.map +1 -0
  155. package/dist/db/migrate.js +244 -0
  156. package/dist/db/recovery.d.ts +11 -0
  157. package/dist/db/recovery.d.ts.map +1 -0
  158. package/dist/db/recovery.js +38 -0
  159. package/dist/db/schema.d.ts +24 -0
  160. package/dist/db/schema.d.ts.map +1 -0
  161. package/dist/db/schema.js +170 -0
  162. package/dist/db/settings-repo.d.ts +8 -0
  163. package/dist/db/settings-repo.d.ts.map +1 -0
  164. package/dist/db/settings-repo.js +27 -0
  165. package/dist/db/tasks-repo.d.ts +26 -0
  166. package/dist/db/tasks-repo.d.ts.map +1 -0
  167. package/dist/db/tasks-repo.js +120 -0
  168. package/dist/db/templates-repo.d.ts +17 -0
  169. package/dist/db/templates-repo.d.ts.map +1 -0
  170. package/dist/db/templates-repo.js +57 -0
  171. package/dist/gui-experimental.cjs +1 -0
  172. package/dist/history.d.ts +60 -0
  173. package/dist/history.d.ts.map +1 -0
  174. package/dist/history.js +70 -0
  175. package/dist/i18n.d.ts +75 -0
  176. package/dist/i18n.d.ts.map +1 -0
  177. package/dist/i18n.js +357 -0
  178. package/dist/index.d.ts +858 -0
  179. package/dist/index.d.ts.map +1 -0
  180. package/dist/index.js +5179 -0
  181. package/dist/integrations.d.ts +72 -0
  182. package/dist/integrations.d.ts.map +1 -0
  183. package/dist/integrations.js +233 -0
  184. package/dist/notifications.d.ts +199 -0
  185. package/dist/notifications.d.ts.map +1 -0
  186. package/dist/notifications.js +967 -0
  187. package/dist/profiles.d.ts +60 -0
  188. package/dist/profiles.d.ts.map +1 -0
  189. package/dist/profiles.js +227 -0
  190. package/dist/rpc.d.ts +3806 -0
  191. package/dist/rpc.d.ts.map +1 -0
  192. package/dist/rpc.js +1507 -0
  193. package/dist/schtasks.d.ts +32 -0
  194. package/dist/schtasks.d.ts.map +1 -0
  195. package/dist/schtasks.js +45 -0
  196. package/dist/server.d.ts +128 -0
  197. package/dist/server.d.ts.map +1 -0
  198. package/dist/server.js +2413 -0
  199. package/dist/settings.d.ts +389 -0
  200. package/dist/settings.d.ts.map +1 -0
  201. package/dist/settings.js +770 -0
  202. package/dist/shared/jobs-view.d.ts +59 -0
  203. package/dist/shared/jobs-view.d.ts.map +1 -0
  204. package/dist/shared/jobs-view.js +146 -0
  205. package/dist/skill.d.ts +15 -0
  206. package/dist/skill.d.ts.map +1 -0
  207. package/dist/skill.js +93 -0
  208. package/dist/task-transfer.d.ts +252 -0
  209. package/dist/task-transfer.d.ts.map +1 -0
  210. package/dist/task-transfer.js +628 -0
  211. package/dist/templates.d.ts +57 -0
  212. package/dist/templates.d.ts.map +1 -0
  213. package/dist/templates.js +16 -0
  214. package/dist/types.d.ts +96 -0
  215. package/dist/types.d.ts.map +1 -0
  216. package/dist/types.js +130 -0
  217. package/dist/version.d.ts +8 -0
  218. package/dist/version.d.ts.map +1 -0
  219. package/dist/version.js +27 -0
  220. package/dist/workspaces.d.ts +113 -0
  221. package/dist/workspaces.d.ts.map +1 -0
  222. package/dist/workspaces.js +393 -0
  223. package/docs/ARCHITECTURE.md +457 -0
  224. package/docs/COMPATIBILITY.md +233 -0
  225. package/docs/CONCEPT.md +230 -0
  226. package/docs/CROSS_PLATFORM.ru.md +150 -0
  227. package/docs/CROSS_PLATFORM.zh.md +146 -0
  228. package/docs/FAQ.md +52 -0
  229. package/docs/FAQ.ru.md +53 -0
  230. package/docs/FAQ.zh.md +43 -0
  231. package/docs/FEATURES.md +698 -0
  232. package/docs/FEATURES.zh.md +655 -0
  233. package/docs/LOCAL-AI.md +300 -0
  234. package/docs/MIGRATION.md +355 -0
  235. package/docs/README.ru.md +268 -0
  236. package/docs/README.zh.md +305 -0
  237. package/docs/SAVINGS.md +61 -0
  238. package/docs/SAVINGS.ru.md +60 -0
  239. package/docs/SAVINGS.zh.md +52 -0
  240. package/docs/V1-V2-COMPATIBILITY-PLAN.md +366 -0
  241. package/docs/ZH-LOCALE-PLAN.md +324 -0
  242. package/docs/dashboard.png +0 -0
  243. package/docs/spikes/local-model-structured-output.md +81 -0
  244. package/docs/spikes/ollama-qwen3-4b-smoke.json +28 -0
  245. package/docs/spikes/ollama-qwen3-4b.json +163 -0
  246. package/gui-experimental.cjs +9 -0
  247. package/index.js +1 -0
  248. package/locales/en.json +780 -0
  249. package/locales/ru.json +780 -0
  250. package/locales/zh.json +780 -0
  251. package/package.json +133 -13
  252. package/scripts/bench-local.mjs +321 -0
  253. package/scripts/check-zh-locale.mjs +218 -0
  254. package/scripts/demo-dashboard.mjs +209 -0
  255. package/scripts/run-tests.mjs +236 -0
  256. package/scripts/spike-local-structured.mjs +182 -0
  257. package/scripts/test-locale.mjs +45 -0
  258. package/skills/scheduled-job-best-practices/SKILL.md +158 -0
  259. package/skills/scheduled-job-best-practices/references/recipes.md +163 -0
  260. package/src/core/analytics.ts +424 -0
  261. package/src/core/audit.ts +418 -0
  262. package/src/core/cron-to-schtasks.ts +288 -0
  263. package/src/core/dry-run.ts +601 -0
  264. package/src/core/file-watcher.ts +245 -0
  265. package/src/core/git-trigger.ts +391 -0
  266. package/src/core/glob.ts +226 -0
  267. package/src/core/local-ai.ts +173 -0
  268. package/src/core/lock.ts +219 -0
  269. package/src/core/matrix.ts +947 -0
  270. package/src/core/native-notify.ts +157 -0
  271. package/src/core/one-shot.ts +189 -0
  272. package/src/core/otel.ts +128 -0
  273. package/src/core/permissions.ts +200 -0
  274. package/src/core/prometheus.ts +215 -0
  275. package/src/core/ps-wrapper.ts +1140 -0
  276. package/src/core/record-history.ts +615 -0
  277. package/src/core/retention.ts +141 -0
  278. package/src/core/savings.ts +150 -0
  279. package/src/core/schedule-gate.ts +253 -0
  280. package/src/core/schedule-v2.ts +668 -0
  281. package/src/core/scheduler/index.ts +82 -0
  282. package/src/core/scheduler/linux.ts +257 -0
  283. package/src/core/scheduler/logs.ts +37 -0
  284. package/src/core/scheduler/mac.ts +270 -0
  285. package/src/core/scheduler/posix.ts +114 -0
  286. package/src/core/scheduler/registry.ts +99 -0
  287. package/src/core/scheduler/types.ts +90 -0
  288. package/src/core/scheduler/windows.ts +711 -0
  289. package/src/core/secrets.ts +503 -0
  290. package/src/core/self-analysis.ts +744 -0
  291. package/src/core/session.ts +150 -0
  292. package/src/core/shutdown.ts +69 -0
  293. package/src/core/structured-log.ts +214 -0
  294. package/src/core/summary.ts +318 -0
  295. package/src/core/telegram.ts +436 -0
  296. package/src/core/triage-chain.ts +125 -0
  297. package/src/core/triage-compare.ts +277 -0
  298. package/src/core/triage-rules.ts +238 -0
  299. package/src/core/triage-shadow.ts +240 -0
  300. package/src/core/triage-worker.ts +344 -0
  301. package/src/core/triage.ts +366 -0
  302. package/src/core/watch-paths.ts +70 -0
  303. package/src/core/wrappers/bash.ts +532 -0
  304. package/src/db/git-state-repo.ts +62 -0
  305. package/src/db/history-repo.ts +492 -0
  306. package/src/db/index.ts +166 -0
  307. package/src/db/metrics-repo.ts +170 -0
  308. package/src/db/migrate.ts +328 -0
  309. package/src/db/recovery.ts +46 -0
  310. package/src/db/schema.ts +188 -0
  311. package/src/db/settings-repo.ts +31 -0
  312. package/src/db/tasks-repo.ts +162 -0
  313. package/src/db/templates-repo.ts +77 -0
  314. package/src/gui.tsx +5222 -0
  315. package/src/history.ts +128 -0
  316. package/src/i18n.ts +413 -0
  317. package/src/index.ts +6605 -0
  318. package/src/integrations.ts +297 -0
  319. package/src/notifications.ts +1346 -0
  320. package/src/profiles.ts +254 -0
  321. package/src/rpc.ts +1609 -0
  322. package/src/schtasks.ts +75 -0
  323. package/src/server.ts +2662 -0
  324. package/src/settings.ts +1369 -0
  325. package/src/shared/jobs-view.ts +188 -0
  326. package/src/skill.ts +113 -0
  327. package/src/task-transfer.ts +944 -0
  328. package/src/templates.ts +67 -0
  329. package/src/tui-v1.tsx +341 -0
  330. package/src/tui.tsx +329 -0
  331. package/src/types.ts +191 -0
  332. package/src/version.ts +27 -0
  333. package/src/workspaces.ts +487 -0
@@ -0,0 +1,233 @@
1
+ # Совместимость версий OpenCode
2
+
3
+ Единый контракт по версиям OpenCode, на которые рассчитан пакет. Источник истины
4
+ для README, CI и тестов: если числа здесь и в коде расходятся — правим здесь и
5
+ синхронизируем остальное.
6
+
7
+ ## Матрица версий
8
+
9
+ | Линия | Минимум | Проверяем | Статус | Точка входа |
10
+ |---|---|---|---|---|
11
+ | **V1** (`1.x`) | `1.18.29` | `1.19.5` (ветка `1.19.x`) | поддерживается с `1.5.6` | `plugin` в конфиге, SDK `@opencode-ai/plugin` |
12
+ | **V2** (`2.x`) | `2.2.7` | `2.2.7` и `2.3.0` (CI job `compat-v2`) | поддерживается с `1.0.0` | `plugins` в конфиге, SDK `@opencode/plugin` |
13
+
14
+ ## Матрица поверхности V1 / V2
15
+
16
+ | Возможность | V1 (`>=1.18.29`) | V2 (`>=2.2.7`) | Комментарий |
17
+ |---|---|---|---|
18
+ | 26 инструментов агента | да, `tool()`; без `options.codemode` | да, `ctx.tool.transform`; `options: { codemode: true }` | имена, схемы и обработчики совпадают |
19
+ | Хуки (tool / session / event / config) | да, строковые ключи в `Hooks` | да, типизированные домены `ctx.*` | API есть, но плагин его **не использует** — см. ниже |
20
+ | TUI-панель «Планировщик» | да, `src/tui-v1.tsx`; маршрут `/scheduler` + снимок в сайдбаре | да, `src/tui.tsx`; reactive store | **обе линии**, один модуль `./tui` |
21
+ | GUI-панель | **нет** | да | subpath `@opencode/plugin/gui` в V1 отсутствует |
22
+ | RPC-методы (`get_platform` и др.) | **нет** | да | subpath `@opencode/plugin/rpc` в V1 отсутствует |
23
+ | HTTP-dashboard | да | да | не зависит от plugin API |
24
+ | DAG, matrix, gates, история, уведомления | да | да | общее ядро |
25
+ | SQLite-состояние | да | да | `<PLUGIN_DIR>/scheduler.db` |
26
+ | Ключ конфига | `plugin` | `plugins` | ключ своей линии; см. «Конфигурация по линиям» |
27
+
28
+ **Явно:** GUI и RPC — только V2. TUI — обе линии: `package.json` объявляет
29
+ `exports["./tui"] = "./src/tui.tsx"` (как в документации OpenCode для
30
+ пакетов-плагинов), а сам модуль отдаёт `{ ...v2Tui, tui: tuiV1 }`: V2 читает
31
+ `setup`, V1 — `tui`. Пакет не обещает GUI/RPC в V1 и не подменяет TUI-панель
32
+ заглушкой.
33
+
34
+ **Конфигурация по линиям.** Ключ выбирает загрузчик OpenCode, а не плагин: сам
35
+ пакет не читает ни `plugin`, ни `plugins`, поэтому чужое поле не может уронить
36
+ его код. V1 подключается ключом `plugin` в `opencode.jsonc`, V2 — ключом
37
+ `plugins` или командой `opencode plugin add opencode-windows-scheduler`. Оба
38
+ ключа одновременно не нужны. Примеры для обеих линий — в README (en/ru/zh).
39
+
40
+ **TUI в V1.** `src/tui-v1.tsx` реализует `TuiPluginModule` и живёт на тех же
41
+ данных, что V2: `getJobsView`, `groupJobsForDisplay`, `statusIcon`,
42
+ `formatJobLog`. Возможности V1 TUI:
43
+
44
+ - маршрут `/scheduler` — полный список задач, выбор и действия
45
+ run / pause / resume / log; после каждого обновления маршрут
46
+ перерегистрируется, поэтому данные свежие;
47
+ - слот `sidebar_content` — снимок списка на момент регистрации: V1 API не
48
+ возвращает функцию отписки от слота, поэтому перерисовать его нельзя;
49
+ - команды палитры — действия, открытие панели, refresh, переход по списку
50
+ (`Ctrl+Shift+J`, `Ctrl+Shift+↑/↓`, `Ctrl+Shift+Enter`);
51
+ - выбранная задача хранится в `api.kv` (`opencode-windows-scheduler.selected`);
52
+ - таймер 5 секунд и отписки снимаются в `api.lifecycle.onDispose`.
53
+
54
+ Ограничение слота — не регрессия, а свойство V1 API; в V2 панель обновляется
55
+ через reactive store `ctx.storage`.
56
+
57
+ **Хуки не используются осознанно.** Плагин не подписывается ни на
58
+ `ctx.tool.hook`, `ctx.permission.hook` и `ctx.event.subscribe` в V2, ни на
59
+ `Hooks.tool.execute.before/after`, `Hooks.event`, `Hooks.permission.ask` в V1:
60
+
61
+ - аудит — обёртка `withAudit` вокруг каждого инструмента в `createToolSpecs`,
62
+ поэтому правила журнала одинаковы в обеих линиях и не зависят от hook-API;
63
+ - permissions — `resolvePermissions`/`buildOpencodeConfig` из
64
+ `src/core/permissions.ts` в env фонового запуска, а не перехват вызовов;
65
+ - события — инструмент `emit_event`, file-watcher и git-trigger, поднятые в
66
+ `createRuntime`.
67
+
68
+ Следствие для Д3: V1-адаптеру не нужны хуки — достаточно общих handlers и
69
+ `createRuntime`. `test-docs` следит, чтобы общий код не начал ссылаться на
70
+ V2-only домены без обновления этого раздела.
71
+
72
+ **Единая выгрузка.** Обе линии используют один `createShutdownHandler(runtime,
73
+ registrations)`: `shutdownGate.begin()` → освобождение регистраций →
74
+ `runtime.dispose()` → закрытие dashboard → ожидание активных in-process
75
+ операций → `closeDb()`. V2 отдаёт этот cleanup из `setup(ctx)`, V1 — из
76
+ `server()` (З3.1); порядок и таймаут `15_000` мс общие.
77
+
78
+ **Двойной экспорт.** В `src/index.ts`:
79
+
80
+ - `const v2Plugin = Plugin.define({ id, setup })` — entrypoint V2;
81
+ - `const v1Plugin: V1PluginModule = { id, server }` — entrypoint V1, `server()`
82
+ вызывает `createV1Hooks()`;
83
+ - `export default { ...v2Plugin, ...v1Plugin }` — каждая линия читает свои поля
84
+ (`setup` или `server`) и игнорирует чужие.
85
+
86
+ `createV1Hooks()` поднимает то же ядро (`createRuntime`), собирает те же
87
+ `createToolSpecs`, навешивает тот же `withAudit`, конвертирует `Tool.Result` в
88
+ V1 `ToolResult` (`{ output, metadata }`) и возвращает `Hooks` с `tool` и
89
+ `dispose`. Дашборд общий — `startSchedulerDashboard()`; GUI, RPC и скиллы в V1
90
+ не регистрируются, потому что их API там нет.
91
+
92
+ **Инструменты в V1.** `createV1Tools(runtime)` отдаёт все 26 спецификаций.
93
+ `args` — это `z.ZodRawShape` (`z.object(...).shape`), как требует V1 `tool()`;
94
+ схемы собраны корневым `zod@4.6.7`, а валидирует их копия `zod@4.1.8` из V1
95
+ SDK — совместимость мажора проверяется в `test-dual-entry.mjs`. У V1 `tool()`
96
+ нет параметра `options`, поэтому `codemode: true` в V1 не передаётся:
97
+ инструменты вызываются обычным способом, а не через code mode. На поведение это
98
+ не влияет — обработчики, аудит и результаты общие; отличие только в способе
99
+ вызова агентом.
100
+
101
+ ## Как проверяется совместимость
102
+
103
+ | Проверка | Что покрывает |
104
+ |---|---|
105
+ | `test-dual-entry.mjs` | форму default export (`id`, `setup`, `server`), `createV1Hooks` → `tool` + `dispose`, 26 инструментов, совпадение имён с V2-реестром `createToolHandlers`, кросс-версию zod |
106
+ | `test-v1-integration.mjs` | реальный V1-путь: `server({ directory })`, изолированные `OPENCODE_SCHEDULER_HOME` и порт дашборда, три read-only инструмента, повторный `dispose` |
107
+ | `test-docs.mjs` | контракт в документации и коде: `exports["./tui"]`, `sidebar_content`, ключи `plugin`/`plugins`, инварианты состояния |
108
+ | CI `compat-v1` / `compat-v2` | отдельные jobs: V1 SDK `1.19.x` и V2 SDK `2.3.0` (устанавливается поверх `2.2.7`), не блокируют матрицу трёх ОС |
109
+
110
+ Полная загрузка через OpenCode CLI требует модели и рабочих кредов, поэтому в
111
+ CI она не запускается: `run` с боевыми ключами остаётся ручной проверкой.
112
+ Автоматически доказывается уровень entrypoint и реального `server()`, включая
113
+ SQLite, recovery и регистрацию инструментов.
114
+
115
+ ## Где зафиксированы версии
116
+
117
+ | Что | Где | Значение |
118
+ |---|---|---|
119
+ | V2, сборка и runtime | `dependencies["@opencode/plugin"]` | `^2.2.7` |
120
+ | V2, схемы инструментов | `dependencies["@opencode/schema"]` | `^2.2.7` |
121
+ | V1, типы адаптера | `devDependencies["@opencode-ai/plugin"]` | `1.19.5` (pinned) |
122
+
123
+ `peerDependencies` намеренно не объявляются: plugin API — не runtime-зависимость
124
+ пакета, его предоставляет сам OpenCode. Пин V1 в `devDependencies` нужен, чтобы
125
+ адаптер компилировался против типов реальной V1-версии, а не «примерно похожей».
126
+ Изменение любого из этих трёх значений без правки таблицы роняет `test-docs`.
127
+
128
+ ## Почему минимум V1 — 1.18.29
129
+
130
+ Двойная совместимость в одном пакете включается объектом
131
+ `{ ...Plugin.define({ id, setup }), async server() {...} }`: V2 вызывает
132
+ `setup()`, V1 вызывает `server()`. Этот способ появился в OpenCode `1.18.29`.
133
+ До него V1 умел только `server()`, а V2 — только `setup()`, поэтому один
134
+ default export не мог обслуживать обе линии. Для версий ниже нужен отдельный
135
+ legacy-entrypoint; в `1.5.6` его нет.
136
+
137
+ Проверено по реестру npm: версия `1.18.29` опубликована, последняя V1 — `1.19.5`.
138
+
139
+ ## Почему минимум V2 — 2.2.7
140
+
141
+ Проверено по опубликованным типам `@opencode/plugin` (47 версий линии `2.x`):
142
+
143
+ | API | Появилось | Комментарий |
144
+ |---|---|---|
145
+ | `Plugin.define({ id, setup })` | `2.0.0` | ядро плагина |
146
+ | `ctx.tool.transform(editor => ...)` | `2.0.0` | регистрация инструментов |
147
+ | домены `ctx.*` (`location`, `storage`, `event`, `tool`, `session`, `permission`, `agent`, `shell`, `skill`, `command`, `mcp`, `worktree`, `rpc`) | `2.0.0` | набор одинаков с `2.2.7` |
148
+ | subpath `./gui` | `2.2.0` | в `2.1.4` ещё отсутствует (`404`) |
149
+ | subpath `./tui`, `./rpc` (через `./*`) | `2.0.0` | |
150
+
151
+ Минимум выставлен по **2.2.7**, а не по `2.0.0`, сознательно:
152
+
153
+ 1. GUI — часть поверхности пакета (`exports` содержит `./gui-experimental`), а
154
+ subpath `/gui` появился только в `2.2.0`.
155
+ 2. Пакет собирается против типов `2.2.7` и объявляет зависимость `^2.2.7`.
156
+ Версии ниже не проверяются, а значит не поддерживаются — обещать их нельзя.
157
+ 3. Между `2.2.7` и `2.3.0` контракт `Plugin.define` и `ctx.tool.transform` не
158
+ менялся, поэтому `2.3.0` проходит как проверочная версия.
159
+
160
+ Ядро (инструменты, хуки, SQLite, планировщик) технически работает и на `2.0.0`,
161
+ но GUI-часть там не загрузится. Поддержка `2.0.0–2.1.x` — отдельное решение,
162
+ в `1.5.6` его нет.
163
+
164
+ ## Контракт V1
165
+
166
+ Всё ниже — из `@opencode-ai/plugin@1.19.5` (последняя V1-версия SDK).
167
+
168
+ **Экспорты пакета:** `.`, `./tool`, `./tui`, `./v2/*`. Subpath `/gui` и `/rpc`
169
+ отсутствуют — GUI-панель и RPC-методы в V1 недоступны.
170
+
171
+ **Тип модуля:**
172
+
173
+ ```ts
174
+ type PluginInput = {
175
+ client; project; directory; worktree; serverUrl; $
176
+ experimental_workspace: { register(type, adapter): void }
177
+ }
178
+ type Plugin = (input: PluginInput, options?: Record<string, unknown>) => Promise<Hooks>
179
+ type PluginModule = { id?: string; server: Plugin; tui?: never }
180
+ ```
181
+
182
+ **Хуки (`Hooks`):** `dispose`, `event`, `config`, `tool` (карта инструментов),
183
+ `tool.execute.before`, `tool.execute.after`, `permission.ask`, `chat.message`,
184
+ `chat.params`, `chat.headers`, `command.execute.before`, `shell.env`, `auth`,
185
+ `provider`, а также группа `experimental.*`.
186
+
187
+ **Инструменты:** `tool({ description, args, execute })`, где `args` — raw shape
188
+ Zod-объекта. `@opencode-ai/plugin@1.19.5` зависит от `zod@4.1.8`, а пакет — от
189
+ `zod@^4.6.7`: мажор совпадает, отдельная копия zod для V1 не нужна. `execute`
190
+ получает `(args, context)` и возвращает `string` либо `{ title, output, metadata, attachments }`.
191
+
192
+ **TUI:** отдельный subpath `@opencode-ai/plugin/tui`; модуль TUI регистрируется
193
+ не через `setup(ctx)`, а через TUI-API V1 (`api.slots`, `api.route`, `api.kv`,
194
+ `api.command`). В `1.5.6` это `src/tui-v1.tsx`, который отдаётся из того же
195
+ `exports["./tui"]`, что и V2-модуль.
196
+
197
+ ## Чего в V1 нет
198
+
199
+ | Возможность | Причина |
200
+ |---|---|
201
+ | GUI-панель | нет subpath `@opencode-ai/plugin/gui` |
202
+ | RPC-методы | нет subpath `@opencode-ai/plugin/rpc` |
203
+ | `ctx.storage` | контекст V1 не предоставляет storage; состояние — SQLite пакета |
204
+ | Типизированные домены (`ctx.tool.hook`, `ctx.event.subscribe`) | в V1 хуки — строковые ключи в объекте `Hooks`; плагин не использует ни те, ни другие |
205
+
206
+ ## Инварианты состояния
207
+
208
+ Эти значения не меняются ни при переходе на dual-support в `1.5.6`, ни при
209
+ rename в `agent-steward` (`2.0.0`): иначе пользователи теряют историю, задачи,
210
+ настройки и уже созданные записи в планировщике ОС. Значения проверяются
211
+ `test-docs` по исходникам.
212
+
213
+ | Что | Значение | Где |
214
+ |---|---|---|
215
+ | `plugin id` | `opencode-windows-scheduler` | `src/index.ts`, `Plugin.define({ id })` |
216
+ | Каталог состояния (default) | Windows: `%APPDATA%\opencode\windows-scheduler`; macOS/Linux: `$XDG_CONFIG_HOME/opencode/windows-scheduler` или `~/.config/opencode/windows-scheduler` | `src/profiles.ts` |
217
+ | Каталог нестандартного профиля | `<каталог состояния>/profiles/<profile>` | `src/profiles.ts` |
218
+ | SQLite | `<PLUGIN_DIR>/scheduler.db`; `OPENCODE_SCHEDULER_DB` — только для тестов | `src/db/index.ts` |
219
+ | Логи, обёртки, locks | `<PLUGIN_DIR>/logs`, `<PLUGIN_DIR>/wrappers`, `<PLUGIN_DIR>/locks` | `src/types.ts` |
220
+ | Промпты и env-файлы задач | `<PLUGIN_DIR>/prompts`, `<PLUGIN_DIR>/env` | `src/index.ts` |
221
+ | Секреты | `<PLUGIN_DIR>/secrets.json`, `<PLUGIN_DIR>/secrets.key` | `src/core/secrets.ts` |
222
+ | Префикс задач Windows | `\OpenCode\windows-scheduler\`; профиль: `\OpenCode\windows-scheduler-<profile>\` | `src/core/scheduler/windows.ts` |
223
+ | Блок crontab | `# >>> opencode-scheduler:<folder> >>>` … `# <<< opencode-scheduler:<folder> <<<` (legacy-блок без суффикса читается) | `src/core/scheduler/linux.ts` |
224
+ | launchd label | `com.opencode.scheduler.<name>` | `src/core/scheduler/mac.ts` |
225
+
226
+ Rename `2.0.0` меняет только npm-имя пакета (`agent-steward@0.0.2`): `plugin id`,
227
+ пути, имена файлов БД/логов и префиксы задач остаются прежними (П7.2).
228
+
229
+ ## Связанные документы
230
+
231
+ - План работ: `docs/V1-V2-COMPATIBILITY-PLAN.md`
232
+ - Переносимость ОС и путей: `CROSS_PLATFORM.md`
233
+ - Миграция пользователей OpenCode V1 → V2: <https://opencode.ai/docs/migrate-v1>
@@ -0,0 +1,230 @@
1
+ # CONCEPT — Верифицируемая локально-первая оркестрация агент-задач
2
+
3
+ > Статус: черновик цели (north star). Рабочее имя пакета — TBD (см. шаг rename).
4
+ > Это документ-направление: любое решение по фиче сверяется с ним.
5
+
6
+ ## TL;DR
7
+
8
+ Локальные модели слабы в открытом творчестве, но компетентны в ограниченной,
9
+ проверяемой работе. Объективная проверка дёшева и надёжна. Поэтому: дешёвая
10
+ локальная модель пытается сделать **максимум проверяемой работы**; объективный
11
+ гейт решает, принято или эскалировать в дорогое облако; каждый исход учит
12
+ систему — роутинг точнее, локальные модели способнее именно под твои задачи.
13
+ Со временем локальный сетап становится личной, приватной, дешёвой и всё более
14
+ умной рабочей силой.
15
+
16
+ Это и есть продукт. Всё остальное — обвязка.
17
+
18
+ ---
19
+
20
+ ## 1. Проблема
21
+
22
+ Разработчику, который хочет автономной agent-работы, сегодня доступны три
23
+ плохих варианта:
24
+
25
+ 1. **Не автоматизировать** — рутина (починить тесты, обновить зависимости,
26
+ бойлерплейт, извлечение, мелкие трансформации) остаётся ручной.
27
+ 2. **Автоматизировать в облаке** — токены на каждый прогон, код уходит наружу,
28
+ нет контроля над тем, что именно исполняется и куда течёт.
29
+ 3. **Автоматизировать локально наивно** — слабая модель молно выдаёт брак,
30
+ падает, двоится; доверия нет, затею бросают.
31
+
32
+ Корень всех трёх: **нет слоя, который делает агент-труд одновременно дешёвым,
33
+ приватным и проверяемо надёжным.**
34
+
35
+ - OpenCode даёт агентов, но не даёт супервизии: нет capability-роутинга,
36
+ объективных гейтов, честной экономии, learning-loop.
37
+ - Облачные оркестраторы дают масштаб, но не приватность и не локальную экономию.
38
+ - Swarm-фреймворки дают коллаборацию, но не надёжность и не экономию.
39
+
40
+ Ниша пуста: **локально-первая, верифицируемая, компаундящаяся оркестрация**.
41
+
42
+ ## 2. Ключевой инсайт
43
+
44
+ Слабость локальных моделей — не приговор, а ограничение, обходимое архитектурой:
45
+
46
+ - Локаль тянет **ограниченные, хорошо scaffolding-нутые, объективно проверяемые**
47
+ задачи. Это и есть масса реальной рутины.
48
+ - **Объективный гейт** (тесты / линт / схема / diff-applies / команда) дёшев и
49
+ не врёт. Он позволяет натравливать локаль на максимум задач: брак ловится и
50
+ эскалируется, а не уезжает в прод.
51
+ - Исходы гейта — **бесплатная разметка**: они учат роутинг («какие типы задач
52
+ локаль тянет») и копят gate-passed датасет для прокачки весов.
53
+
54
+ Проверка — не надзор, а **двигатель экономики и обучения**.
55
+
56
+ ## 3. Что это такое
57
+
58
+ **Фреймворк-супервизор поверх OpenCode**: локальный control plane, который
59
+ принимает миссии (ad-hoc или по расписанию), раскладывает их на шаги с ролями,
60
+ назначает каждый шаг **самому дешёвому способному исполнителю** (локаль →
61
+ облако только при провале гейта), объективно верифицирует результат, честно
62
+ считает экономию и компаундится — с каждой задачей дешевле и умнее под
63
+ конкретного пользователя.
64
+
65
+ Метафора: бригадир смешанной бригады. Дешёвые локальные подмастерья делают
66
+ ограниченную работу под инспекцией; дорогие облачные специалисты вызываются,
67
+ только когда инспекция завалила подмастерье; каждая инспекция делает
68
+ подмастерьев лучше именно в твоих ремёслах.
69
+
70
+ ## 4. Цель и критерии приёмки (north star)
71
+
72
+ Четыре столпа. Любая фича/ADR сверяется с ними; при конфликте порядок такой:
73
+ **надёжно > приватно > дёшево > краткосрочные фичи**, explore — управляемая
74
+ инвестиция «дёшево-сегодня» в «компаунд-завтра».
75
+
76
+ | Столп | Что значит | Метрика |
77
+ |---|---|---|
78
+ | **Дёшево** | локаль закрывает максимум gate-able задач | net-экономия $ (честная контрфактика), local share %, escalation rate, time overhead |
79
+ | **Приватно** | control plane, данные, аудит, triage локальны | % инференса/данных локально; cloud-egress только explicit и залогирован |
80
+ | **Надёжно** | ноль тихих отказов/двойных прогонов/fake-done/порчи репо | trust-инциденты = 0; гейт независим от self-report; полнота аудита |
81
+ | **Компаундится** | success rate и экономия растут под пользователя | тренд local success_rate ↑, eval-lift адаптеров, рост scaffolding-библиотеки |
82
+
83
+ Цель одним предложением: **разработчик оставляет AI-агентам свою рутину —
84
+ дёшево, приватно, надёжно — и его локальный сетап с каждой неделей работает
85
+ лучше и дешевле именно под его задачи.**
86
+
87
+ ## 5. Способности (что он делает)
88
+
89
+ - **Миссия** = цель + scope + явный критерий приёмки (гейт). Без критерия —
90
+ не миссия, а лотерея.
91
+ - **Декомпозиция** на шаги/роли (planner → implementer → reviewer …).
92
+ - **Capability-aware роутинг**: локаль по умолчанию по capability-карте;
93
+ облако — эскалация; explore/exploit баланс (учимся на неопределённых,
94
+ выжимаем на известных).
95
+ - **Объективная верификация** (keystone): провал → эскалация / ретрай / откат;
96
+ никогда «готово» на слово агента.
97
+ - **Честная экономика**: savings ledger (net-контрфактика с учётом эскалаций и
98
+ overhead), токены/стоимость по шагам и моделям.
99
+ - **Полный аудит**: кто, каким инструментом, какой файл, когда, почему
100
+ эскалировали.
101
+ - **Learning-loop**: capability-карта по типам задач → scaffolding/few-shot из
102
+ успешных решений → eval-harness → (staged) LoRA-адаптеры на gate-passed
103
+ датасете.
104
+ - **Автономность**: ad-hoc или расписание; переживает ребут; не двоится; не
105
+ зависает; leases/locks/таймауты.
106
+
107
+ ## 6. Исполнительный цикл (его задачи)
108
+
109
+ 1. Принять миссию + критерий приёмки.
110
+ 2. Разложить на шаги, назначить роли.
111
+ 3. Выбрать исполнителя шага (локаль first по capability-карте).
112
+ 4. Выполнить шаг.
113
+ 5. Прогнать объективный гейт.
114
+ 6. Pass → записать экономию + пример + метку (+ training-record).
115
+ Fail → эскалация / ретрай / откат + метка.
116
+ 7. Собрать артефакт миссии (diff/PR, отчёт, аудит-трейл).
117
+ 8. Отчитаться честно (savings, success rate, эскалации, overhead).
118
+ 9. Обновить роутинг/eval; периодически — дообучить адаптер.
119
+
120
+ ## 7. Архитектура (слои)
121
+
122
+ ```
123
+ [ триггеры: ad-hoc CLI/RPC | scheduler | file | git | mcp-event ] ← обвязка
124
+ │
125
+ [ mission intake: цель + scope + критерий приёмки (гейт) ]
126
+ │
127
+ [ planner: декомпозиция на шаги/роли ]
128
+ │
129
+ [ router: capability-карта → локаль first; explore/exploit ]
130
+ │ │ эскалация
131
+ │ ▼
132
+ │ [ облачные модели (fallback / тяжёлая артиллерия) ]
133
+ ▼
134
+ [ executor: OpenCode-агенты (локальные / облачные) ]
135
+ │
136
+ [ GATE: объективная верификация (tests/lint/schema/diff/cmd) ] ← keystone
137
+ │ pass │ fail
138
+ ▼ ▼
139
+ [ ledger: savings/audit/metrics ] [ escalate / retry / rollback ]
140
+ │
141
+ [ learning: capability-карта → scaffolding → eval → LoRA (staged) ]
142
+ │
143
+ [ control plane: локальный, приватный, аудит, dashboard ]
144
+ ```
145
+
146
+ Локально-первым является **control plane и роутинг**; инференс — гибрид
147
+ (локаль максимум, облако эскалация). Приватность = данные/аудит/управление
148
+ локальны, а не «ни одного облачного токена».
149
+
150
+ ## 8. Границы (чем НЕ является)
151
+
152
+ - Не open-ended AGI-swarm: миссии ограниченные, с явным критерием приёмки.
153
+ - Не замена способной облачной модели на сложном: облако — эскалация.
154
+ - Не отмена человеческого ревью критичного: гейт поднимает пол, не потолок.
155
+ - Не облачный SaaS и не multi-machine: локальный control plane, одна машина.
156
+ - Не «плагин-планировщик»: scheduler/уведомления/аналитика — триггеры и
157
+ обвязка, не ядро.
158
+
159
+ ## 9. Душа: flywheel
160
+
161
+ Больше задач → больше локальных попыток → больше исходов гейта → точнее
162
+ capability-карта и больше примеров → выше local success → больше экономия и
163
+ сильнее адаптеры → ещё больше задач выгодно гнать через локаль.
164
+
165
+ Этот цикл и есть продукт. Персональная, приватная, компаундящаяся capability —
166
+ ров, которого нет ни у статичного облака, ни у OpenCode core, ни у swarm-ов.
167
+
168
+ ## 10. Реальность железа (ограничение, учтённое в дизайне)
169
+
170
+ Целевая стартовая конфигурация — потребительская (пример: RTX 3050 8 ГБ,
171
+ 16 ГБ RAM). Отсюда:
172
+ - инференс локально: QLoRA/квант 3–8B;
173
+ - обучение: только QLoRA 3–4B, low-rank, накопленным gate-passed датасетом,
174
+ пакетами, а не онлайн;
175
+ - поэтому прокачка staged: сначала scaffolding/роутинг (дёшево, сразу),
176
+ веса — когда датасет и железо позволяют.
177
+ Дизайн не зависит от конкретного железа: capability-карта и гейты работают и на
178
+ слабой, и на сильной локали; меняется лишь доля задач, которую тянет локаль.
179
+
180
+ ## 11. Как поймём, что пришли (definition of done концепции)
181
+
182
+ Вертикальный срез работает end-to-end и измеримо:
183
+ 1. ad-hoc миссия с явным гейтом принята и разложена;
184
+ 2. шаги смаршрутированы локаль-first по capability-карте;
185
+ 3. гейт объективно верифицировал; провал экалировался/откатился без тихих
186
+ отказов;
187
+ 4. ledger показал честную net-экономию и escalation rate;
188
+ 5. learning-loop обновил capability-карту и положил пример/scaffolding;
189
+ 6. на фикс-наборе задач за N недель: local success_rate ↑ и net-экономия ↑
190
+ при неизменном качестве (eval не деградировал).
191
+
192
+ Когда 1–6 воспроизводимо — концепция достигнута; всё дальнейшее = масштаб
193
+ (больше типов задач, больше машин, сильнее адаптеры).
194
+
195
+ ## 12. Открытые вопросы / риски (честно)
196
+
197
+ - Качество локального вердикта на пограничных задачах → держим правила/пороги и
198
+ shadow-режим, а не слепую веру модели.
199
+ - Cost of verification (прогоны тестов) → учитывать в net-экономике, кэшировать.
200
+ - Explore может тратить впустую → capped explore-бюджет, bandit по типам задач.
201
+ - Датасет для весов копится медленно → staged-прокачка, не обещать онлайн-LoRA.
202
+ - Prompt-injection даже при gate → гейт + аудит + allowedTools как пол, а не
203
+ потолок; критичное — человеку.
204
+
205
+ ## 13. Стратегия развития: от плагина к фреймворку
206
+
207
+ Наша эволюция строится на двух столпах и постепенной абстракции:
208
+
209
+ ### 13.1 Локальный интеллект
210
+
211
+ Максимум проверяемой работы на локальных моделях с компандингом (обучением на успешных гейтах). Локаль тянет ограниченные, хорошо сформулированные, объективно проверяемые задачи — масса реальной рутины. Объективный гейт (тесты, линт, схема, diff-applies) дёшев и не врёт, поэтому локаль направляется на максимум задач: брак ловится и эскалируется, а не уезжает в прод. Исходы гейта — бесплатная разметка, которая учит роутинг и копит gate-passed датасет.
212
+
213
+ ### 13.2 Мультиагентная оркестрация
214
+
215
+ Ролевая декомпозиция миссий на шаги (planner → implementer → reviewer …). Каждый шаг назначается самому дешёвому способному исполнителю — локаль first, облако только при провале гейта. Облако используется для эскалации сложных задач, обеспечивая экономию и приватность.
216
+
217
+ ### 13.3 Непрерывное улучшение Control Plane
218
+
219
+ Существующий функционал (планировщик, DAG, матрицы, Quality Gates, GUI, аудит) — это фундамент доверия, а не отдельный продукт. Он дорабатывается наравне с ядром: локальность, приватность, наблюдаемость, гарантии отсутствия тихих отказов.
220
+
221
+ ### 13.4 Путь к универсальности
222
+
223
+ - **Этап 1:** глубокая интеграция с OpenCode V1 и V2 (текущий): один пакет, dual export, общее ядро.
224
+ - **Этап 2:** абстракция слоя исполнения (Agent Executor Interface).
225
+ - **Этап 3:** универсальный фреймворк оркестрации, совместимый с любым агентом через MCP или стандартные API.
226
+
227
+ ---
228
+
229
+ *Любое изменение в репозитории, которое не двигает хотя бы один столп из §4 и
230
+ не согласуется с §8, — не цель, а шум.*
@@ -0,0 +1,150 @@
1
+ # Кроссплатформенность: Windows → macOS → Linux
2
+
3
+ Плагин больше не привязан к `schtasks`. Планировщик вынесен в абстрактный слой с тремя реализациями,
4
+ а обёртки запуска генерируются под целевую ОС.
5
+
6
+ Translations: [English](../CROSS_PLATFORM.md) · [中文](CROSS_PLATFORM.zh.md)
7
+
8
+ ## Архитектура
9
+
10
+ ```
11
+ src/
12
+ index.ts # инструменты, RPC, жизненный цикл плагина
13
+ gui.tsx # панель GUI (заголовок берётся из RPC)
14
+ server.ts # веб-дашборд (заголовок динамический)
15
+ core/
16
+ scheduler/
17
+ types.ts # SchedulerBackend, CreateTaskOptions, RunTaskResult
18
+ index.ts # фабрика createSchedulerBackend() + getSchedulerTitle()
19
+ windows.ts # WindowsScheduler (schtasks)
20
+ linux.ts # LinuxScheduler (crontab)
21
+ mac.ts # MacScheduler (launchd / LaunchAgents)
22
+ posix.ts # общая база для Linux/macOS (реестр задач)
23
+ registry.ts # персистентный реестр задач POSIX-бэкендов
24
+ logs.ts # чтение логов задач (кроссплатформенно)
25
+ wrappers/
26
+ bash.ts # генератор .sh-обёрток для Linux/macOS
27
+ ps-wrapper.ts # .ps1/.cmd-обёртки для Windows (как раньше)
28
+ record-history.ts # метрики/история + retry/цепочки (через бэкенд)
29
+ cron-to-schtasks.ts # cron → schtasks (только Windows)
30
+ ```
31
+
32
+ ### Интерфейс
33
+
34
+ ```ts
35
+ interface SchedulerBackend {
36
+ readonly platform: NodeJS.Platform;
37
+ readonly title: string; // «Планировщик Windows» / «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
+ Фабрика выбирает реализацию по `process.platform`:
48
+ `win32 → WindowsScheduler`, `darwin → MacScheduler`, остальные → `LinuxScheduler`.
49
+
50
+ ## Как работает каждая ОС
51
+
52
+ ### Windows (поведение не изменилось)
53
+ - Задачи регистрируются в Планировщике Windows через `schtasks` в папке `\OpenCode\windows-scheduler\`.
54
+ - Обёртка: `run-task.ps1` + персональный `run-<name>.cmd` в `%APPDATA%\opencode\windows-scheduler\wrapper`.
55
+ - Логи: `%APPDATA%\opencode\windows-scheduler\logs\<name>.log`.
56
+ - cron конвертируется в schtasks (`convertCronToSchTasks`) — поддерживается тот же набор шаблонов.
57
+
58
+ ### Linux
59
+ - Задачи живут в управляемом блоке `crontab`:
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
+ - Пауза = строка с префиксом `# PAUSED: ` (блок пересобирается из реестра).
67
+ - Задачи с триггером `file` в crontab не попадают — их запускает FileWatchManager плагина.
68
+ - Обёртка: `~/.config/opencode/windows-scheduler/wrapper/run-<name>.sh` (chmod 0755).
69
+ - Полный cron-синтаксис (в отличие от Windows), т.к. crontab понимает его нативно.
70
+ - Удаление/пересборка — только своего блока, остальные строки `crontab` не трогаются.
71
+
72
+ ### macOS
73
+ - Задачи — LaunchAgent-плисты `~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`.
74
+ - Расписание: `StartInterval` для `* * * * *` и `*/N`, `StartCalendarInterval` для `M * * * *`,
75
+ `M H * * *`, `M H * * D`.
76
+ - Пауза = `launchctl unload -w`, возобновление = `launchctl load -w`.
77
+ - Обёртка — тот же `.sh`, что и на Linux; пути конфигов:
78
+ `~/.config/opencode/windows-scheduler/` (или `$XDG_CONFIG_HOME`).
79
+
80
+ ### Общая POSIX-обёртка (`.sh`)
81
+ - `cd` в рабочую директорию, `opencode run` с промптом из файла.
82
+ - Логи пишутся в файл через `>>` и дублируются метками времени.
83
+ - Блокировка через атомарный `mkdir` — защита от параллельных запусков.
84
+ - Таймаут: дочерний процесс + watchdog (`TERM`, затем `KILL`).
85
+ - Quality Gate: `bash -lc "<команда>"` (аналог `cmd.exe /c` на Windows).
86
+ - Метрики: `node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"` —
87
+ тот же контракт, что и в PowerShell-обёртке, поэтому история/метрики/retry/цепочки работают везде.
88
+ - `PATH` дополняется `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, `~/.bun/bin`.
89
+
90
+ ## Матрица возможностей
91
+
92
+ | Возможность | Windows | Linux | macOS |
93
+ |---|---|---|---|
94
+ | Бэкенд планировщика | `schtasks` | `crontab` | `launchd` LaunchAgents |
95
+ | Нативный cron-поднабор | `* * * * *`, `*/N * * * *` (N ≤ 1439, 60 % N = 0), `M * * * *`, `M H * * *`, `M H * * D` | полный cron | тот же поднабор, что на Windows |
96
+ | Остальные cron-выражения | minute-poll + schedule gate | нативный cron | minute-poll + schedule gate |
97
+ | `*/N` в дне месяца / дне недели | не нативно → poll | нативно | не нативно → poll |
98
+ | Пауза / возобновление | `schtasks /change /disable` / `/enable` | строка `# PAUSED:` в управляемом блоке | `launchctl unload -w` / `load -w` |
99
+ | Файловые триггеры | in-process `FileWatchManager` | так же | так же |
100
+ | Обёртки задач | `.cmd` + `.ps1` | `.sh` | `.sh` |
101
+ | Логи | `%APPDATA%\opencode\windows-scheduler\logs` | `~/.config/opencode/windows-scheduler/logs` | как на Linux |
102
+ | Защита `secrets.key` | `icacls` (только владелец) + `chmod` как fallback | `chmod 0600` | `chmod 0600` |
103
+ | Дашборд | `127.0.0.1`, динамический заголовок | так же | так же |
104
+ | DAG / matrix / quality gates / уведомления | в плагине, не зависят от ОС | так же | так же |
105
+
106
+ ### Компромиссы
107
+
108
+ 1. **Minute-poll.** Cron-выражения вне нативного поднабора и задачи с чужой IANA-зоной
109
+ запускаются планировщиком ОС каждую минуту; `schedule-gate` решает, выполнять ли запуск.
110
+ Цена — один короткоживущий процесс-обёртка на задачу в минуту.
111
+ 2. **`M H */N * *` сознательно не конвертируется в `schtasks /sc DAILY /mo N`.**
112
+ Cron считает дни от 1-го числа каждого месяца и сбрасывается на границе месяца;
113
+ `/mo N` считает дни от даты создания задачи и не сбрасывается. Это не эквивалентные
114
+ расписания, поэтому выражение остаётся в poll-режиме. Нативный вариант потребовал бы
115
+ `MONTHLY` с явным списком `/d`, а не `DAILY /mo N`.
116
+ 3. **DST.** Шлюз работает с локальным настенным временем. Несуществующее время
117
+ (переход весной) пропускается; неоднозначное время (переход осенью) выполняется
118
+ в первом вхождении.
119
+ 4. **`*/N * * * *` на Windows** нативно только при `60 % N = 0` и `N ≤ 1439`.
120
+ Иначе задача уходит в poll-режим: `schtasks /mo N` считает от момента создания,
121
+ а cron — от начала часа.
122
+ 5. **POSIX-обёртки, crontab и launchd не исполнялись на реальных Linux/macOS**
123
+ (см. «Ограничения»); синтаксис и экранирование покрыты только тестами.
124
+
125
+ ## GUI и дашборд
126
+ - Заголовок динамический: на Windows — «Планировщик Windows», на macOS/Linux — «OpenCode Scheduler».
127
+ - Источник заголовка — новый RPC-метод `get_platform` → `{ platform, title }`.
128
+ - Заголовок используется и в панели GUI, и в fallback-панели ошибки, и в `<title>/<h1>` веб-дашборда.
129
+ - Кнопки, статусы, таблица, DAG и метрики не зависят от ОС.
130
+ - Описания инструментов (`schedule_task` и др.) подставляют актуальное название планировщика.
131
+
132
+ ## Сборка и проверки
133
+ - `npm run build` — OK, ошибок нет.
134
+ - `npm run build:gui` — OK (`gui-experimental.cjs`, ~47.7 kB).
135
+ - Проверено в runtime:
136
+ - заголовки для win32/darwin/linux;
137
+ - `cronToLaunchdSchedule` на нескольких выражениях;
138
+ - живой `listTasks()` на Windows — задачи возвращаются короткими именами (без префикса);
139
+ - экранирование `shellQuote` (кавычки, пробелы, кириллица);
140
+ - импорт `dist/index.js` проходит, `dist` не тянет `schtasks.js` напрямую.
141
+
142
+ ## Ограничения и что проверить на реальных машинах
143
+ 1. `.sh`-обёртки и crontab/launchd **не исполнялись** — на текущей Windows-машине нет `bash`/WSL.
144
+ Синтаксис и экранирование проверены вручную; нужен прогон на Linux и macOS.
145
+ 2. cron → launchd поддерживает тот же ограниченный набор шаблонов, что и Windows
146
+ (`* * * * *`, `*/N * * * *`, `M * * * *`, `M H * * *`, `M H * * D`).
147
+ На Linux доступен полный cron.
148
+ 3. Префикс задач Windows (`\OpenCode\windows-scheduler\`) и id плагина сохранены для обратной совместимости.
149
+ 4. `src/schtasks.ts` оставлен как тонкий shim для старых скриптов (`test-create.cjs`, `test-run.cjs`),
150
+ вся логика теперь в `core/scheduler/windows.ts`.