agent-steward 0.0.0-stage → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (334) hide show
  1. package/CHANGELOG.md +376 -0
  2. package/CROSS_PLATFORM.md +149 -0
  3. package/LICENSE +21 -0
  4. package/README.md +314 -2
  5. package/ROADMAP-STRATEGY.md +147 -0
  6. package/ROADMAP.md +1069 -0
  7. package/dist/core/analytics.d.ts +132 -0
  8. package/dist/core/analytics.d.ts.map +1 -0
  9. package/dist/core/analytics.js +290 -0
  10. package/dist/core/audit.d.ts +96 -0
  11. package/dist/core/audit.d.ts.map +1 -0
  12. package/dist/core/audit.js +297 -0
  13. package/dist/core/cron-to-schtasks.d.ts +20 -0
  14. package/dist/core/cron-to-schtasks.d.ts.map +1 -0
  15. package/dist/core/cron-to-schtasks.js +250 -0
  16. package/dist/core/dry-run.d.ts +102 -0
  17. package/dist/core/dry-run.d.ts.map +1 -0
  18. package/dist/core/dry-run.js +447 -0
  19. package/dist/core/file-watcher.d.ts +31 -0
  20. package/dist/core/file-watcher.d.ts.map +1 -0
  21. package/dist/core/file-watcher.js +186 -0
  22. package/dist/core/git-trigger.d.ts +82 -0
  23. package/dist/core/git-trigger.d.ts.map +1 -0
  24. package/dist/core/git-trigger.js +312 -0
  25. package/dist/core/glob.d.ts +38 -0
  26. package/dist/core/glob.d.ts.map +1 -0
  27. package/dist/core/glob.js +233 -0
  28. package/dist/core/local-ai.d.ts +52 -0
  29. package/dist/core/local-ai.d.ts.map +1 -0
  30. package/dist/core/local-ai.js +119 -0
  31. package/dist/core/lock.d.ts +57 -0
  32. package/dist/core/lock.d.ts.map +1 -0
  33. package/dist/core/lock.js +195 -0
  34. package/dist/core/matrix.d.ts +167 -0
  35. package/dist/core/matrix.d.ts.map +1 -0
  36. package/dist/core/matrix.js +724 -0
  37. package/dist/core/native-notify.d.ts +36 -0
  38. package/dist/core/native-notify.d.ts.map +1 -0
  39. package/dist/core/native-notify.js +113 -0
  40. package/dist/core/one-shot.d.ts +68 -0
  41. package/dist/core/one-shot.d.ts.map +1 -0
  42. package/dist/core/one-shot.js +139 -0
  43. package/dist/core/otel.d.ts +4 -0
  44. package/dist/core/otel.d.ts.map +1 -0
  45. package/dist/core/otel.js +98 -0
  46. package/dist/core/permissions.d.ts +69 -0
  47. package/dist/core/permissions.d.ts.map +1 -0
  48. package/dist/core/permissions.js +143 -0
  49. package/dist/core/prometheus.d.ts +23 -0
  50. package/dist/core/prometheus.d.ts.map +1 -0
  51. package/dist/core/prometheus.js +146 -0
  52. package/dist/core/ps-wrapper.d.ts +73 -0
  53. package/dist/core/ps-wrapper.d.ts.map +1 -0
  54. package/dist/core/ps-wrapper.js +1071 -0
  55. package/dist/core/record-history.d.ts +25 -0
  56. package/dist/core/record-history.d.ts.map +1 -0
  57. package/dist/core/record-history.js +471 -0
  58. package/dist/core/retention.d.ts +29 -0
  59. package/dist/core/retention.d.ts.map +1 -0
  60. package/dist/core/retention.js +98 -0
  61. package/dist/core/savings.d.ts +70 -0
  62. package/dist/core/savings.d.ts.map +1 -0
  63. package/dist/core/savings.js +87 -0
  64. package/dist/core/schedule-gate.d.ts +2 -0
  65. package/dist/core/schedule-gate.d.ts.map +1 -0
  66. package/dist/core/schedule-gate.js +211 -0
  67. package/dist/core/schedule-v2.d.ts +116 -0
  68. package/dist/core/schedule-v2.d.ts.map +1 -0
  69. package/dist/core/schedule-v2.js +586 -0
  70. package/dist/core/scheduler/index.d.ts +32 -0
  71. package/dist/core/scheduler/index.d.ts.map +1 -0
  72. package/dist/core/scheduler/index.js +63 -0
  73. package/dist/core/scheduler/linux.d.ts +44 -0
  74. package/dist/core/scheduler/linux.d.ts.map +1 -0
  75. package/dist/core/scheduler/linux.js +225 -0
  76. package/dist/core/scheduler/logs.d.ts +11 -0
  77. package/dist/core/scheduler/logs.d.ts.map +1 -0
  78. package/dist/core/scheduler/logs.js +34 -0
  79. package/dist/core/scheduler/mac.d.ts +40 -0
  80. package/dist/core/scheduler/mac.d.ts.map +1 -0
  81. package/dist/core/scheduler/mac.js +207 -0
  82. package/dist/core/scheduler/posix.d.ts +40 -0
  83. package/dist/core/scheduler/posix.d.ts.map +1 -0
  84. package/dist/core/scheduler/posix.js +89 -0
  85. package/dist/core/scheduler/registry.d.ts +41 -0
  86. package/dist/core/scheduler/registry.d.ts.map +1 -0
  87. package/dist/core/scheduler/registry.js +57 -0
  88. package/dist/core/scheduler/types.d.ts +86 -0
  89. package/dist/core/scheduler/types.d.ts.map +1 -0
  90. package/dist/core/scheduler/types.js +1 -0
  91. package/dist/core/scheduler/windows.d.ts +99 -0
  92. package/dist/core/scheduler/windows.d.ts.map +1 -0
  93. package/dist/core/scheduler/windows.js +596 -0
  94. package/dist/core/secrets.d.ts +66 -0
  95. package/dist/core/secrets.d.ts.map +1 -0
  96. package/dist/core/secrets.js +433 -0
  97. package/dist/core/self-analysis.d.ts +117 -0
  98. package/dist/core/self-analysis.d.ts.map +1 -0
  99. package/dist/core/self-analysis.js +539 -0
  100. package/dist/core/self-analysis.test.d.ts +2 -0
  101. package/dist/core/self-analysis.test.d.ts.map +1 -0
  102. package/dist/core/self-analysis.test.js +219 -0
  103. package/dist/core/session.d.ts +42 -0
  104. package/dist/core/session.d.ts.map +1 -0
  105. package/dist/core/session.js +134 -0
  106. package/dist/core/shutdown.d.ts +26 -0
  107. package/dist/core/shutdown.d.ts.map +1 -0
  108. package/dist/core/shutdown.js +49 -0
  109. package/dist/core/structured-log.d.ts +84 -0
  110. package/dist/core/structured-log.d.ts.map +1 -0
  111. package/dist/core/structured-log.js +146 -0
  112. package/dist/core/summary.d.ts +69 -0
  113. package/dist/core/summary.d.ts.map +1 -0
  114. package/dist/core/summary.js +250 -0
  115. package/dist/core/telegram.d.ts +55 -0
  116. package/dist/core/telegram.d.ts.map +1 -0
  117. package/dist/core/telegram.js +344 -0
  118. package/dist/core/triage-chain.d.ts +40 -0
  119. package/dist/core/triage-chain.d.ts.map +1 -0
  120. package/dist/core/triage-chain.js +80 -0
  121. package/dist/core/triage-compare.d.ts +68 -0
  122. package/dist/core/triage-compare.d.ts.map +1 -0
  123. package/dist/core/triage-compare.js +184 -0
  124. package/dist/core/triage-rules.d.ts +23 -0
  125. package/dist/core/triage-rules.d.ts.map +1 -0
  126. package/dist/core/triage-rules.js +196 -0
  127. package/dist/core/triage-shadow.d.ts +91 -0
  128. package/dist/core/triage-shadow.d.ts.map +1 -0
  129. package/dist/core/triage-shadow.js +160 -0
  130. package/dist/core/triage-worker.d.ts +55 -0
  131. package/dist/core/triage-worker.d.ts.map +1 -0
  132. package/dist/core/triage-worker.js +314 -0
  133. package/dist/core/triage.d.ts +76 -0
  134. package/dist/core/triage.d.ts.map +1 -0
  135. package/dist/core/triage.js +271 -0
  136. package/dist/core/watch-paths.d.ts +6 -0
  137. package/dist/core/watch-paths.d.ts.map +1 -0
  138. package/dist/core/watch-paths.js +62 -0
  139. package/dist/core/wrappers/bash.d.ts +95 -0
  140. package/dist/core/wrappers/bash.d.ts.map +1 -0
  141. package/dist/core/wrappers/bash.js +413 -0
  142. package/dist/db/git-state-repo.d.ts +16 -0
  143. package/dist/db/git-state-repo.d.ts.map +1 -0
  144. package/dist/db/git-state-repo.js +38 -0
  145. package/dist/db/history-repo.d.ts +110 -0
  146. package/dist/db/history-repo.d.ts.map +1 -0
  147. package/dist/db/history-repo.js +300 -0
  148. package/dist/db/index.d.ts +47 -0
  149. package/dist/db/index.d.ts.map +1 -0
  150. package/dist/db/index.js +120 -0
  151. package/dist/db/metrics-repo.d.ts +46 -0
  152. package/dist/db/metrics-repo.d.ts.map +1 -0
  153. package/dist/db/metrics-repo.js +103 -0
  154. package/dist/db/migrate.d.ts +24 -0
  155. package/dist/db/migrate.d.ts.map +1 -0
  156. package/dist/db/migrate.js +244 -0
  157. package/dist/db/recovery.d.ts +11 -0
  158. package/dist/db/recovery.d.ts.map +1 -0
  159. package/dist/db/recovery.js +38 -0
  160. package/dist/db/schema.d.ts +24 -0
  161. package/dist/db/schema.d.ts.map +1 -0
  162. package/dist/db/schema.js +170 -0
  163. package/dist/db/settings-repo.d.ts +8 -0
  164. package/dist/db/settings-repo.d.ts.map +1 -0
  165. package/dist/db/settings-repo.js +27 -0
  166. package/dist/db/tasks-repo.d.ts +26 -0
  167. package/dist/db/tasks-repo.d.ts.map +1 -0
  168. package/dist/db/tasks-repo.js +120 -0
  169. package/dist/db/templates-repo.d.ts +17 -0
  170. package/dist/db/templates-repo.d.ts.map +1 -0
  171. package/dist/db/templates-repo.js +57 -0
  172. package/dist/gui-experimental.cjs +1 -0
  173. package/dist/history.d.ts +60 -0
  174. package/dist/history.d.ts.map +1 -0
  175. package/dist/history.js +70 -0
  176. package/dist/i18n.d.ts +75 -0
  177. package/dist/i18n.d.ts.map +1 -0
  178. package/dist/i18n.js +357 -0
  179. package/dist/index.d.ts +858 -0
  180. package/dist/index.d.ts.map +1 -0
  181. package/dist/index.js +5179 -0
  182. package/dist/integrations.d.ts +72 -0
  183. package/dist/integrations.d.ts.map +1 -0
  184. package/dist/integrations.js +233 -0
  185. package/dist/notifications.d.ts +199 -0
  186. package/dist/notifications.d.ts.map +1 -0
  187. package/dist/notifications.js +967 -0
  188. package/dist/profiles.d.ts +60 -0
  189. package/dist/profiles.d.ts.map +1 -0
  190. package/dist/profiles.js +227 -0
  191. package/dist/rpc.d.ts +3806 -0
  192. package/dist/rpc.d.ts.map +1 -0
  193. package/dist/rpc.js +1507 -0
  194. package/dist/schtasks.d.ts +32 -0
  195. package/dist/schtasks.d.ts.map +1 -0
  196. package/dist/schtasks.js +45 -0
  197. package/dist/server.d.ts +128 -0
  198. package/dist/server.d.ts.map +1 -0
  199. package/dist/server.js +2413 -0
  200. package/dist/settings.d.ts +389 -0
  201. package/dist/settings.d.ts.map +1 -0
  202. package/dist/settings.js +770 -0
  203. package/dist/shared/jobs-view.d.ts +59 -0
  204. package/dist/shared/jobs-view.d.ts.map +1 -0
  205. package/dist/shared/jobs-view.js +146 -0
  206. package/dist/skill.d.ts +15 -0
  207. package/dist/skill.d.ts.map +1 -0
  208. package/dist/skill.js +93 -0
  209. package/dist/task-transfer.d.ts +252 -0
  210. package/dist/task-transfer.d.ts.map +1 -0
  211. package/dist/task-transfer.js +628 -0
  212. package/dist/templates.d.ts +57 -0
  213. package/dist/templates.d.ts.map +1 -0
  214. package/dist/templates.js +16 -0
  215. package/dist/types.d.ts +96 -0
  216. package/dist/types.d.ts.map +1 -0
  217. package/dist/types.js +130 -0
  218. package/dist/version.d.ts +8 -0
  219. package/dist/version.d.ts.map +1 -0
  220. package/dist/version.js +27 -0
  221. package/dist/workspaces.d.ts +113 -0
  222. package/dist/workspaces.d.ts.map +1 -0
  223. package/dist/workspaces.js +393 -0
  224. package/docs/ARCHITECTURE.md +457 -0
  225. package/docs/COMPATIBILITY.md +233 -0
  226. package/docs/CONCEPT.md +230 -0
  227. package/docs/CROSS_PLATFORM.ru.md +150 -0
  228. package/docs/CROSS_PLATFORM.zh.md +146 -0
  229. package/docs/FAQ.md +52 -0
  230. package/docs/FAQ.ru.md +53 -0
  231. package/docs/FAQ.zh.md +43 -0
  232. package/docs/FEATURES.md +698 -0
  233. package/docs/FEATURES.zh.md +655 -0
  234. package/docs/LOCAL-AI.md +300 -0
  235. package/docs/MIGRATION.md +355 -0
  236. package/docs/README.ru.md +268 -0
  237. package/docs/README.zh.md +305 -0
  238. package/docs/SAVINGS.md +61 -0
  239. package/docs/SAVINGS.ru.md +60 -0
  240. package/docs/SAVINGS.zh.md +52 -0
  241. package/docs/V1-V2-COMPATIBILITY-PLAN.md +366 -0
  242. package/docs/ZH-LOCALE-PLAN.md +324 -0
  243. package/docs/dashboard.png +0 -0
  244. package/docs/spikes/local-model-structured-output.md +81 -0
  245. package/docs/spikes/ollama-qwen3-4b-smoke.json +28 -0
  246. package/docs/spikes/ollama-qwen3-4b.json +163 -0
  247. package/gui-experimental.cjs +9 -0
  248. package/index.js +1 -0
  249. package/locales/en.json +780 -0
  250. package/locales/ru.json +780 -0
  251. package/locales/zh.json +780 -0
  252. package/package.json +149 -4
  253. package/scripts/bench-local.mjs +321 -0
  254. package/scripts/check-zh-locale.mjs +218 -0
  255. package/scripts/demo-dashboard.mjs +209 -0
  256. package/scripts/run-tests.mjs +236 -0
  257. package/scripts/spike-local-structured.mjs +182 -0
  258. package/scripts/test-locale.mjs +45 -0
  259. package/skills/scheduled-job-best-practices/SKILL.md +158 -0
  260. package/skills/scheduled-job-best-practices/references/recipes.md +163 -0
  261. package/src/core/analytics.ts +424 -0
  262. package/src/core/audit.ts +418 -0
  263. package/src/core/cron-to-schtasks.ts +288 -0
  264. package/src/core/dry-run.ts +601 -0
  265. package/src/core/file-watcher.ts +245 -0
  266. package/src/core/git-trigger.ts +391 -0
  267. package/src/core/glob.ts +226 -0
  268. package/src/core/local-ai.ts +173 -0
  269. package/src/core/lock.ts +219 -0
  270. package/src/core/matrix.ts +947 -0
  271. package/src/core/native-notify.ts +157 -0
  272. package/src/core/one-shot.ts +189 -0
  273. package/src/core/otel.ts +128 -0
  274. package/src/core/permissions.ts +200 -0
  275. package/src/core/prometheus.ts +215 -0
  276. package/src/core/ps-wrapper.ts +1140 -0
  277. package/src/core/record-history.ts +615 -0
  278. package/src/core/retention.ts +141 -0
  279. package/src/core/savings.ts +150 -0
  280. package/src/core/schedule-gate.ts +253 -0
  281. package/src/core/schedule-v2.ts +668 -0
  282. package/src/core/scheduler/index.ts +82 -0
  283. package/src/core/scheduler/linux.ts +257 -0
  284. package/src/core/scheduler/logs.ts +37 -0
  285. package/src/core/scheduler/mac.ts +270 -0
  286. package/src/core/scheduler/posix.ts +114 -0
  287. package/src/core/scheduler/registry.ts +99 -0
  288. package/src/core/scheduler/types.ts +90 -0
  289. package/src/core/scheduler/windows.ts +711 -0
  290. package/src/core/secrets.ts +503 -0
  291. package/src/core/self-analysis.ts +744 -0
  292. package/src/core/session.ts +150 -0
  293. package/src/core/shutdown.ts +69 -0
  294. package/src/core/structured-log.ts +214 -0
  295. package/src/core/summary.ts +318 -0
  296. package/src/core/telegram.ts +436 -0
  297. package/src/core/triage-chain.ts +125 -0
  298. package/src/core/triage-compare.ts +277 -0
  299. package/src/core/triage-rules.ts +238 -0
  300. package/src/core/triage-shadow.ts +240 -0
  301. package/src/core/triage-worker.ts +344 -0
  302. package/src/core/triage.ts +366 -0
  303. package/src/core/watch-paths.ts +70 -0
  304. package/src/core/wrappers/bash.ts +532 -0
  305. package/src/db/git-state-repo.ts +62 -0
  306. package/src/db/history-repo.ts +492 -0
  307. package/src/db/index.ts +166 -0
  308. package/src/db/metrics-repo.ts +170 -0
  309. package/src/db/migrate.ts +328 -0
  310. package/src/db/recovery.ts +46 -0
  311. package/src/db/schema.ts +188 -0
  312. package/src/db/settings-repo.ts +31 -0
  313. package/src/db/tasks-repo.ts +162 -0
  314. package/src/db/templates-repo.ts +77 -0
  315. package/src/gui.tsx +5222 -0
  316. package/src/history.ts +128 -0
  317. package/src/i18n.ts +413 -0
  318. package/src/index.ts +6605 -0
  319. package/src/integrations.ts +297 -0
  320. package/src/notifications.ts +1346 -0
  321. package/src/profiles.ts +254 -0
  322. package/src/rpc.ts +1609 -0
  323. package/src/schtasks.ts +75 -0
  324. package/src/server.ts +2662 -0
  325. package/src/settings.ts +1369 -0
  326. package/src/shared/jobs-view.ts +188 -0
  327. package/src/skill.ts +113 -0
  328. package/src/task-transfer.ts +944 -0
  329. package/src/templates.ts +67 -0
  330. package/src/tui-v1.tsx +341 -0
  331. package/src/tui.tsx +329 -0
  332. package/src/types.ts +191 -0
  333. package/src/version.ts +27 -0
  334. package/src/workspaces.ts +487 -0
@@ -0,0 +1,60 @@
1
+ # Счётчик «сэкономлено $»
2
+
3
+ Дашборд и `get_analytics` показывают KPI **«Сэкономлено»**. Это **оценка**, а не
4
+ бухгалтерский факт: рядом с суммой стоит пометка «оценка» и ссылка на эту
5
+ страницу.
6
+
7
+ Translations: [English](SAVINGS.md) · [中文](SAVINGS.zh.md)
8
+
9
+ ## Methodology
10
+
11
+ Контрфактика строится по истории запусков (`history` в SQLite).
12
+
13
+ 1. Берутся записи окна анализа, кроме незавершённых (`status = "running"`).
14
+ 2. В оценку попадает запуск, у которого **есть токены** (`tokens > 0`) и
15
+ **не записана стоимость** (`costUsd` пустой или `0`). Обычно это локальная
16
+ модель (Ollama) или уже оплаченная подписка: токены потрачены, но деньги за
17
+ них не списаны.
18
+ 3. Для каждого такого запуска считается гипотетическая облачная стоимость:
19
+
20
+ ```
21
+ saved = tokens / 1000 × referenceCostPer1kTokensUsd
22
+ ```
23
+
24
+ 4. Сумма складывается по всем запускам окна и разбивается по задачам
25
+ (топ-10 по экономии).
26
+
27
+ Эталонная цена по умолчанию — **$0.01 за 1k токенов** (смесь входа и выхода
28
+ облачного провайдера среднего класса), константа
29
+ `CLOUD_REFERENCE_COST_PER_1K_TOKENS_USD` в `src/core/savings.ts`. Запуски с
30
+ записанной стоимостью в экономию не попадают: за них деньги уже списаны, и
31
+ сравнивать нечего.
32
+
33
+ ## Что оценка не учитывает
34
+
35
+ - кеш промптов, скидки и пакетные тарифы;
36
+ - разницу цен входных и выходных токенов;
37
+ - запуски без токенов (например, чистый shell): экономии там может и не быть;
38
+ - запуски, где стоимость не записана по ошибке, а не потому что она нулевая —
39
+ такие записи завышают оценку.
40
+
41
+ Поэтому счётчик отвечает на вопрос «сколько бы это стоило в облаке по
42
+ эталонной цене», а не «сколько денег вернулось на счёт».
43
+
44
+ ## API
45
+
46
+ `get_analytics` возвращает `report.savings`:
47
+
48
+ | Поле | Значение |
49
+ | --- | --- |
50
+ | `kind` | всегда `estimate` |
51
+ | `savedUsd` | оценка экономии, USD |
52
+ | `runs` | запусков в контрфактике |
53
+ | `tokens` | токенов в этих запусках |
54
+ | `actualCostUsd` | записанная стоимость этих же запусков (обычно 0) |
55
+ | `totalCostUsd` | записанная стоимость всех запусков окна |
56
+ | `referenceCostPer1kTokensUsd` | эталонная цена |
57
+ | `methodologyUrl` | ссылка на эту страницу |
58
+ | `byTask` | разбивка `{ taskName, runs, tokens, savedUsd }` |
59
+
60
+ Методика проверяется на фиксированных данных: `test-savings.mjs`, 14 проверок.
@@ -0,0 +1,52 @@
1
+ # 「节省 $」计数器
2
+
3
+ 仪表盘和 `get_analytics` 会显示 **「节省」** KPI。它是**估算**,不是账务事实:
4
+ 金额会标注为估算并链接到本页。
5
+
6
+ Translations: [English](SAVINGS.md) · [Русский](SAVINGS.ru.md)
7
+
8
+ ## 方法
9
+
10
+ 反事实估算基于运行历史(SQLite 中的 `history`)。
11
+
12
+ 1. 取分析窗口内的记录,排除未完成的运行(`status = "running"`)。
13
+ 2. 当一次运行**有 token**(`tokens > 0`)且**没有记录成本**(`costUsd` 为空或 `0`)时,
14
+ 它进入估算。通常是本地模型(Ollama)或已付费订阅:消耗了 token 但未扣费。
15
+ 3. 对每次这样的运行计算假设的云端成本:
16
+
17
+ ```
18
+ saved = tokens / 1000 × referenceCostPer1kTokensUsd
19
+ ```
20
+
21
+ 4. 在窗口内对所有运行求和,并按任务拆分(按节省额取前 10)。
22
+
23
+ 默认参考价格为 **每 1k token $0.01**(中端云厂商输入/输出混合价),即
24
+ `src/core/savings.ts` 中的常量 `CLOUD_REFERENCE_COST_PER_1K_TOKENS_USD`。
25
+ 有记录成本的运行不计入节省:已经扣过费,没什么可对比的。
26
+
27
+ ## 估算未考虑的因素
28
+
29
+ - 提示词缓存、折扣和批量定价;
30
+ - 输入与输出 token 的价格差异;
31
+ - 没有 token 的运行(例如纯 shell 运行):可能根本没有节省;
32
+ - 成本因错误而未记录(而非因为为零)的运行——这类记录会虚增估算。
33
+
34
+ 因此该计数器回答的是「按参考价格在云端要花多少钱」,而不是「实际退回了多少钱」。
35
+
36
+ ## API
37
+
38
+ `get_analytics` 返回 `report.savings`:
39
+
40
+ | 字段 | 值 |
41
+ | --- | --- |
42
+ | `kind` | 始终为 `estimate` |
43
+ | `savedUsd` | 估算节省额,USD |
44
+ | `runs` | 反事实中的运行数 |
45
+ | `tokens` | 这些运行的 token 数 |
46
+ | `actualCostUsd` | 这些运行记录的成本(通常为 0) |
47
+ | `totalCostUsd` | 窗口内所有运行记录的成本 |
48
+ | `referenceCostPer1kTokensUsd` | 参考价格 |
49
+ | `methodologyUrl` | 指向本页的链接 |
50
+ | `byTask` | 拆分 `{ taskName, runs, tokens, savedUsd }` |
51
+
52
+ 该方法在固定数据上验证:`test-savings.mjs`,14 项检查。
@@ -0,0 +1,366 @@
1
+ # План: OpenCode v1 + v2 и переименование в `agent-steward`
2
+
3
+ Статус: план утверждён по структуре, выполнение — по одной подзадаче.
4
+ Версия работ: `opencode-windows-scheduler@1.5.6`.
5
+ Переименование: milestone `2.0.0`, пакет `agent-steward` начинается с `0.0.2`
6
+ (версия `0.0.1` занята placeholder-резервом).
7
+
8
+ ## Принятые решения
9
+
10
+ 1. **Один пакет, два entrypoint.** Официальный паттерн OpenCode:
11
+ default export = `{ ...Plugin.define({ id, setup }), async server() { return v1Plugin } }`.
12
+ V2 вызывает `setup()`, V1 — `server()`. Минимальная версия V1 — `1.18.29`.
13
+ 2. **Ядро общее.** SQLite, планировщик, DAG, matrix, quality gates, dashboard,
14
+ история, уведомления не зависят от версии plugin API и переиспользуются.
15
+ 3. **Границы V1.** В V1 доступны: инструменты, хуки, TUI-плагин
16
+ (`@opencode-ai/plugin/tui`), локальный HTTP-dashboard.
17
+ В V1 **недоступны**: GUI-панель (`@opencode/plugin/gui`) и кастомный RPC
18
+ (`@opencode/plugin/rpc`) — этих subpath в V1-пакете нет.
19
+ 4. **Идентификаторы сохраняем.** `plugin id`, пути SQLite/логов и префикс задач
20
+ планировщика не меняются при 1.5.6 и при rename — иначе потеряется состояние
21
+ пользователей.
22
+ 5. **Режим работы.** Одна подзадача → отчёт → предложения по улучшению →
23
+ ожидание команды «дальше».
24
+
25
+ ## Матрица поверхности
26
+
27
+ | Возможность | V1 (>=1.18.29) | V2 |
28
+ |---|---|---|
29
+ | 26 инструментов агента | да, через `tool()` | да, `ctx.tool.transform` |
30
+ | Хуки (tool/session/event/config) | да, строковые ключи | да, типизированные домены |
31
+ | TUI-панель | да, отдельный `tui` entrypoint | да, текущий `tui.tsx` |
32
+ | GUI-панель | нет | да |
33
+ | RPC-методы | нет | да |
34
+ | Dashboard (HTTP) | да, версионно-независим | да |
35
+ | DAG / matrix / gates / история | да | да |
36
+
37
+ ---
38
+
39
+ ## Деталь Д0. Инфраструктура имени
40
+
41
+ ### Задача З0.1. Зарезервировать `agent-steward`
42
+ - П0.1.1 — создать минимальный placeholder-пакет `agent-steward@0.0.1`
43
+ (README «reserved», LICENSE, repository).
44
+ - П0.1.2 — опубликовать `npm publish --access public`.
45
+ - П0.1.3 — проверить `npm view agent-steward version` = `0.0.1`.
46
+
47
+ ### Задача З0.2. Удалить `opencode-pipeline`
48
+ - П0.2.1 — удалить `packages/opencode-pipeline/`.
49
+ - П0.2.2 — снять пакет с npm (`npm unpublish` при возможности, иначе `npm deprecate`).
50
+ - П0.2.3 — удалить/поправить ссылки: `test-docs.mjs`, `ROADMAP-STRATEGY.md`,
51
+ активные разделы `ROADMAP.md`, `.github/workflows/publish-placeholder.yml`.
52
+ Исторические записи `CHANGELOG.md` не переписываем.
53
+ - П0.2.4 — `npm test` (набор `test-docs`) зелёный.
54
+
55
+ ---
56
+
57
+ ## Деталь Д1. Контракт совместимости
58
+
59
+ ### Задача З1.1. Зафиксировать матрицу версий
60
+ - П1.1.1 — V1: минимум `1.18.29`, проверять `1.19.x`.
61
+ - П1.1.2 — V2: текущая поддерживаемая (`2.x`) — `2.2.7`. ✅
62
+ - П1.1.3 — зафиксировать версии в `package.json` (`peerDependencies` не вводим,
63
+ plugin API не является runtime-зависимостью пакета). ✅
64
+ `dependencies["@opencode/plugin"]` = `^2.2.7`, `devDependencies["@opencode-ai/plugin"]` = `1.19.5`
65
+ (pinned, только типы), `peerDependencies` отсутствуют.
66
+
67
+ ### Задача З1.2. Зафиксировать границы поверхности
68
+ - П1.2.1 — таблица «V1 / V2» в `docs/CROSS_PLATFORM.md` или отдельном документе. ✅
69
+ - П1.2.2 — явно указать: GUI и RPC — только V2; TUI — обе версии. ✅
70
+ - П1.2.3 — README: требование «OpenCode v2» заменить на «V1 >=1.18.29 или V2». ✅
71
+
72
+ ### Задача З1.3. Инварианты состояния
73
+ - П1.3.1 — `plugin id` остаётся `opencode-windows-scheduler` до rename. ✅
74
+ - П1.3.2 — пути `%APPDATA%/opencode/windows-scheduler`, SQLite и логов не меняются. ✅
75
+ - П1.3.3 — префикс задач планировщика не меняется. ✅
76
+
77
+ ---
78
+
79
+ ## Деталь Д2. Извлечение общего ядра
80
+
81
+ ### Задача З2.1. Вынести bootstrap из `setup(ctx)`
82
+ - П2.1.1 — `createRuntime(ctxLike)` с инициализацией БД, миграции, recovery, GC,
83
+ retention, таймеров, watcher/git-trigger. ✅
84
+ - П2.1.2 — `setup(ctx)` V2 вызывает `createRuntime(ctx)` и регистрацию V2. ✅
85
+ - П2.1.3 — `server()` V1 вызывает `createRuntime(v1Context)` и регистрацию V1. ✅
86
+ (`server()` → `createV1Hooks()` → `createRuntime`, те же specs/handlers)
87
+
88
+ ### Задача З2.2. Общий реестр инструментов
89
+ - П2.2.1 — вынести 25 `execute`-функций в `createToolHandlers(runtime)`. ✅
90
+ - П2.2.2 — V2-обёртка `editor.add` остаётся тонкой. ✅
91
+ - П2.2.3 — V1-обёртка `tool()` использует те же handlers. ✅
92
+ (`createV1Hooks` идёт по тем же `createToolSpecs`)
93
+
94
+ ### Задача З2.3. Общие хуки
95
+ - П2.3.1 — проверить и зафиксировать: аудит/permissions/события уже живут в
96
+ общем ядре (`withAudit` в `createToolSpecs`, `core/permissions.ts`, общие
97
+ handlers и триггеры в `createRuntime`). ✅
98
+ - П2.3.2 — V2-домены `ctx.tool.hook`, `ctx.permission.hook`,
99
+ `ctx.event.subscribe` **не используются**: для аудита, permissions и событий
100
+ hook-API не нужен. ✅ (не требуется)
101
+ - П2.3.3 — V1-хуки `Hooks.tool.execute.*`, `Hooks.event`,
102
+ `Hooks.permission.ask` **не используются**; паритет линий достигается общими
103
+ handlers, а не строковыми ключами. ✅ (не требуется)
104
+
105
+ ### Задача З2.4. Единый shutdown
106
+ - П2.4.1 — `createShutdownHandler(runtime, registrations)` — общий сценарий
107
+ выгрузки: `shutdownGate.begin()` → dispose регистраций → `runtime.dispose()`
108
+ → dashboard → `waitForIdle(15_000)` → `closeDb()`. ✅
109
+ - П2.4.2 — V2 возвращает cleanup из `setup()`, V1 — из `server()`. ✅
110
+ (обе линии возвращают `createShutdownHandler(runtime)`)
111
+
112
+ ---
113
+
114
+ ## Деталь Д3. V1-адаптер
115
+
116
+ ### Задача З3.1. Dual export
117
+ - П3.1.1 — `const v2 = Plugin.define({ id, setup })`. ✅ (`v2Plugin`)
118
+ - П3.1.2 — `const v1 = { async server() { ... } }`. ✅ (`v1Plugin` типа
119
+ `V1PluginModule`, `server()` → `createV1Hooks()`)
120
+ - П3.1.3 — `export default { ...v2, ...v1 }`. ✅
121
+ - П3.1.4 — проверить, что V2 игнорирует `server`, а V1 — `setup`. ✅
122
+ (`test-dual-entry.mjs` — модульная проверка формы экспорта и V1-хуков;
123
+ реальная загрузка обеими линиями — в Д4)
124
+
125
+ ### Задача З3.2. Инструменты V1
126
+ - П3.2.1 — замапить 26 инструментов в `tool({ description, args, execute })`. ✅
127
+ (`createV1Tools(runtime)`; тот же `createToolSpecs` и `withAudit`)
128
+ - П3.2.2 — привести args-схемы к формату V1. ✅
129
+ (`toV1ToolArgs(spec)` → `z.object(...).shape`, иначе явная ошибка; схемы
130
+ 4.6.7 читаются zod 4.1.8 из V1 SDK — проверено в `test-dual-entry.mjs`)
131
+ - П3.2.3 — сохранить `codemode`-семантику, если V1 её поддерживает; иначе
132
+ задокументировать отличие. ✅
133
+ (у V1 `tool()` нет `options`; `codemode` не передаётся, отличие описано в
134
+ `docs/COMPATIBILITY.md`; поведение определяют общие handlers)
135
+
136
+ ### Задача З3.3. Хуки V1
137
+ - П3.3.1 — не требуется: аудит — общая обёртка `withAudit`, permissions — env
138
+ фонового запуска (см. П2.3.1). ✅
139
+ - П3.3.2 — не требуется: события — `emit_event`, file-watcher и git-trigger в
140
+ `createRuntime`. ✅
141
+ - П3.3.3 — не требуется: настройки читаются из `settings.json` пакета, а не из
142
+ `Hooks.config`. ✅
143
+
144
+ ### Задача З3.4. TUI V1
145
+ - П3.4.1 — отдельный entrypoint `src/tui-v1.tsx` с `TuiPluginModule`. ✅
146
+ - П3.4.2 — использовать `api.slots.register`, `api.route.register`, `api.kv`. ✅
147
+ - П3.4.3 — сохранить текущую панель «Планировщик» и действия run/pause/resume/log. ✅
148
+ - П3.4.4 — проверить загрузку TUI в V1 >=1.18.29. ✅ статически (типы
149
+ `TuiPluginModule`, `exports["./tui"]`, `tsc` по TUI-файлам); реальная загрузка
150
+ установленным V1 — в Д4.
151
+
152
+ ### Задача З3.5. Конфигурация
153
+ - П3.5.1 — V1 читает `plugin`, V2 — `plugins`; код не должен падать на чужом
154
+ поле. ✅ (плагин не читает конфиг; ключ выбирает загрузчик)
155
+ - П3.5.2 — обновить README-примеры для обеих версий. ✅ (en/ru/zh, таблица
156
+ ключей + отдельные примеры; `test-docs` проверяет оба ключа)
157
+
158
+ ---
159
+
160
+ ## Деталь Д4. Регрессия V2
161
+
162
+ ### Задача З4.1. Entrypoint
163
+ - П4.1.1 — V2 по-прежнему загружает `setup` и 26 инструментов. ✅
164
+ (модульно: `test-dual-entry` импортирует `dist/index.js`, проверяет
165
+ `setup`/`server` и 26 инструментов; реальная загрузка загрузчиком — З5.3)
166
+ - П4.1.2 — GUI и RPC не затронуты. ✅ (`npm run build:gui` — 374.51 kB,
167
+ сборка проходит; `src/gui.tsx`/`src/rpc.ts` не менялись)
168
+
169
+ ### Задача З4.2. Поведение
170
+ - П4.2.1 — DAG, matrix, gates, dashboard, уведомления без изменений. ✅
171
+ (полный `npm test`: 62 скрипта, ни одного `FAIL`; профильные сюиты
172
+ matrix/DAG/gates/dashboard/notifications зелёные)
173
+ - П4.2.2 — существующие 61 набор тестов зелёные. ✅ (фактически 62 скрипта:
174
+ добавлен `test-dual-entry.mjs`; `test-docs` — 80/80)
175
+
176
+ ---
177
+
178
+ ## Деталь Д5. Тесты совместимости
179
+
180
+ ### Задача З5.1. Unit-тесты адаптера
181
+ - П5.1.1 — форма default export: есть `setup` и `server`. ✅
182
+ - П5.1.2 — `server()` возвращает объект с `tool` и хуками. ✅ (`tool` +
183
+ `dispose`, повторная выгрузка безопасна)
184
+ - П5.1.3 — набор имён инструментов совпадает V1/V2. ✅
185
+ (`deepEqual` с `createToolHandlers(null)`)
186
+
187
+ ### Задача З5.2. Интеграция V1
188
+ - П5.2.1 — установить `@opencode-ai/plugin@1.19.x` в тестовый стенд. ✅
189
+ (`1.19.5` уже в `devDependencies`; `test-dual-entry` валидирует схемы его
190
+ собственной копией zod)
191
+ - П5.2.2 — загрузить пакет как V1-плагин, вызвать 2–3 инструмента. ✅
192
+ (`test-v1-integration.mjs`: `server({ directory })`, `list_tasks`,
193
+ `get_metrics`, `get_dashboard_info`, изолированные HOME и порт)
194
+ - П5.2.3 — проверить TUI entrypoint. ✅ статически (`exports["./tui"]`,
195
+ `sidebar_content`, `src/tui-v1.tsx` — проверки `test-docs`); живой запуск
196
+ TUI требует интерактивного OpenCode и остаётся ручным.
197
+
198
+ ### Задача З5.3. Интеграция V2
199
+ - П5.3.1 — текущий V2 smoke-тест. ✅ (модульная форма `setup`/26 инструментов,
200
+ полный `npm test`; реальная загрузка CLI — ручная, см. Д4)
201
+ - П5.3.2 — проверить GUI/RPC. ✅ (`npm run build:gui`, `gui-experimental.cjs`;
202
+ `src/gui.tsx`/`src/rpc.ts` не менялись)
203
+
204
+ ### Задача З5.4. CI
205
+ - П5.4.1 — job `compat-v1` и `compat-v2`. ✅
206
+ - П5.4.2 — не блокировать основные 3 ОС, если V1-стенд недоступен; вынести в
207
+ отдельный job. ✅ (оба job — `ubuntu-latest`, вне матрицы ОС)
208
+
209
+ ---
210
+
211
+ ## Деталь Д6. Релиз 1.5.6
212
+
213
+ ### Задача З6.1. Подготовка
214
+ - П6.1.1 — `package.json` version `1.5.6`.
215
+ - П6.1.2 — CHANGELOG: dual support, границы V1.
216
+ - П6.1.3 — README/CROSS_PLATFORM/FAQ.
217
+
218
+ ### Задача З6.2. Публикация
219
+ - П6.2.1 — полный прогон `test:parallel` + en/zh.
220
+ - П6.2.2 — тег `v1.5.6`, release workflow.
221
+ - П6.2.3 — проверить npm и GitHub Release.
222
+
223
+ ---
224
+
225
+ ## Деталь Д7. Rename 2.0.0 → `agent-steward` 0.0.2
226
+
227
+ - П7.1 — rename-only релиз без фич.
228
+ - П7.2 — сменить `name` пакета, сохранить `plugin id` и пути состояния.
229
+ - П7.3 — старый пакет — thin re-export с deprecation на один major.
230
+ - П7.4 — миграционная инструкция: `plugin`/`plugins`, npm-имя, тег.
231
+ - П7.5 — первый реальный релиз `agent-steward@0.0.2`.
232
+
233
+ ---
234
+
235
+ ## Деталь Д8. За пределами 1.5.6
236
+
237
+ - П8.1 — Agent Executor Interface (абстракция исполнения).
238
+ - П8.2 — вынос OpenCode-адаптера.
239
+ - П8.3 — MCP/standard API для других агентов.
240
+
241
+ ---
242
+
243
+ ## Порядок выполнения
244
+
245
+ 1. Д0 (инфраструктура имени).
246
+ 2. Д1 (контракт).
247
+ 3. Д2 (ядро).
248
+ 4. Д3 (V1-адаптер).
249
+ 5. Д4 (регрессия V2).
250
+ 6. Д5 (тесты).
251
+ 7. Д6 (релиз 1.5.6).
252
+ 8. Д7 (rename, отдельный milestone).
253
+
254
+ ## Статус
255
+
256
+ | Деталь | Статус |
257
+ |---|---|
258
+ | Д0 | ✅ 17.11.2026 |
259
+ | Д1 | ✅ 17.11.2026 |
260
+ | Д2 | ✅ 17.11.2026 |
261
+ | Д3 | ✅ 17.11.2026 |
262
+ | Д4 | ✅ 17.11.2026 (регрессия; реальная загрузка — З5.2/З5.3) |
263
+ | Д5 | ✅ 17.11.2026 |
264
+ | Д6 | в работе (подготовка ✅, публикация ждёт разрешения) |
265
+ | Д7 | отложена |
266
+ | Д8 | отложена |
267
+
268
+ ## Журнал выполнения
269
+
270
+ ### Д0. Инфраструктура имени — ✅ 17.11.2026
271
+
272
+ | Подзадача | Результат |
273
+ |---|---|
274
+ | П0.1.1 | Placeholder `agent-steward@0.0.1` создан во временном каталоге: `package.json`, `README.md`, `LICENSE`. `npm pack --dry-run` — 3 файла, 1.6 kB, без зависимостей и скриптов. |
275
+ | П0.1.2 | `npm publish --access public` — успешно. npm создал служебную stub-версию `0.0.0-stage`, версия `0.0.1` ушла на automated review. |
276
+ | П0.1.3 | Имя зарезервировано: maintainer `deadsno`, пакет существует в реестре. `0.0.1` станет `latest` после завершения проверки; при отказе следующий релиз — `0.0.2`. |
277
+ | П0.2.1 | `packages/opencode-pipeline/` удалена (`git rm -r`), каталог `packages/` исчез. |
278
+ | П0.2.2 | `npm unpublish` отклонён: E403 — granular access token с bypass 2FA не может выполнять деструктивные операции. Fallback: `npm deprecate opencode-pipeline@0.0.1` — применён, сообщение видно в `npm view`. Пакет решено оставить депрекейченным, а не удалять. |
279
+ | П0.2.3 | `test-docs.mjs`: 4 проверки заглушки заменены на «нет локальных пакетов» + «workflow удалён». Workflow `publish-placeholder.yml` удалён. Обновлены `ROADMAP.md` (28.6, 37.1, решение 2, таблица действий) и `ROADMAP-STRATEGY.md` (переименование в `agent-steward`). `CHANGELOG.md` и исторические строки `ROADMAP.md` не тронуты. |
280
+ | П0.2.4 | `node test-docs.mjs` — 42/42. Полный `npm test` (61 сюита) — exit 0, ни одного `FAIL`, все сводки `0 failed`. |
281
+
282
+ Побочный результат: `opencode-windows-scheduler@1.5.5` прошла automated review и стала `latest`.
283
+
284
+ ### Д1. Контракт совместимости — ✅ 17.11.2026
285
+
286
+ | Подзадача | Результат |
287
+ |---|---|
288
+ | П1.1.1 | Создан `docs/COMPATIBILITY.md`: матрица версий (V1 — минимум `1.18.29`, проверочная `1.19.5`), обоснование минимума, контракт V1 (типы `PluginInput`/`Plugin`/`PluginModule`, состав `Hooks`, формат инструментов), таблица «чего в V1 нет». Проверено по реестру: `1.18.29` опубликована; последняя V1 SDK — `1.19.5`; V1 SDK зависит от `zod@4.1.8`, а пакет от `zod@^4.6.7` — мажор совпадает, отдельная копия zod не нужна. `test-docs` расширен на 3 проверки → 45/45. |
289
+ | П1.1.2 | V2-строка заполнена: минимум `2.2.7`, проверяем `2.2.7` и `2.3.0`. Проверено по опубликованным типам всех 47 версий линии `2.x`: `Plugin.define` и `ctx.tool.transform` есть с `2.0.0`; набор доменов `ctx.*` с `2.0.0` совпадает с `2.2.7`; subpath `./gui` отсутствует в `2.1.4` и появляется в `2.2.0`; `./tui` и `./rpc` есть с `2.0.0`; между `2.2.7` и `2.3.0` контракт `Plugin.define`/`tool.transform` не менялся. Минимум выставлен по `2.2.7` (пол сборки и зависимости `^2.2.7`), а не по `2.0.0`: ядро там работает, GUI — нет. Добавлена таблица «что появилось когда» + раздел «Почему минимум V2 — 2.2.7». `test-docs` расширен на 2 проверки → 47/47. |
290
+ | П1.1.3 | В `package.json` добавлена `devDependencies["@opencode-ai/plugin"] = "1.19.5"` (pinned, только типы адаптера); `dependencies["@opencode/plugin"]` остаётся `^2.2.7`; `peerDependencies` не объявляются. `npm install` — 18 пакетов, `package-lock.json` +324 строки; `npm ls` подтверждает `@opencode-ai/plugin@1.19.5` и `@opencode/plugin@2.2.7`. Импорт `@opencode-ai/plugin` и `@opencode-ai/plugin/tool` работает, `tool` — функция. Две копии zod (`4.1.8` внутри V1 SDK, `4.6.7` в корне), мажор один — схемы переиспользуются. В `docs/COMPATIBILITY.md` добавлен раздел «Где зафиксированы версии»; `test-docs` расширен на 3 проверки (пол V2, пин V1, отсутствие peerDependencies) → 50/50. |
291
+ | П1.2.1 | В `docs/COMPATIBILITY.md` добавлен раздел «Матрица поверхности V1 / V2» на 9 строк: инструменты, хуки, TUI, GUI, RPC, dashboard, общее ядро, SQLite, ключ конфига. Выбран отдельный документ, а не `CROSS_PLATFORM.md`: версии и границы поверхности живут в одном источнике истины, `CROSS_PLATFORM.md` остаётся про ОС и пути. |
292
+ | П1.2.2 | В матрице GUI и RPC помечены «**нет**» для V1 (subpath `/gui` и `/rpc` в V1-пакете отсутствуют), TUI — «**обе линии**»: V2 регистрирует панель через `setup(ctx)`, V1 — через отдельный `src/tui-v1.tsx` (З3.4). Под таблицей добавлен явный абзац «GUI и RPC — только V2»; пакет не обещает их в V1 и не подменяет TUI заглушкой. |
293
+ | П1.2.3 | README (en/ru/zh) обновлены: tagline и раздел Install больше не требуют «OpenCode v2», теперь «V1 ≥ 1.18.29 или V2» + ссылка на `docs/COMPATIBILITY.md` (GUI/RPC — только V2, TUI — обе линии). Переводы `docs/README.ru.md` и `docs/README.zh.md` поправлены в том же коммите. |
294
+ | П1.3.1 | `plugin id` остаётся `opencode-windows-scheduler` (`src/index.ts`, `Plugin.define({ id })`). Зафиксировано в разделе «Инварианты состояния»; `test-docs` сверяет значение в коде и документе. |
295
+ | П1.3.2 | Пути состояния сведены в таблицу: Windows `%APPDATA%\opencode\windows-scheduler`, macOS/Linux `$XDG_CONFIG_HOME/opencode/windows-scheduler` или `~/.config/opencode/windows-scheduler`; профили — `<base>/profiles/<name>`; SQLite — `<PLUGIN_DIR>/scheduler.db` (`OPENCODE_SCHEDULER_DB` только для тестов); логи/обёртки/locks/prompts/env и `secrets.json`/`secrets.key` — под `<PLUGIN_DIR>`. `test-docs` сверяет `profiles.ts`, `db/index.ts`, `types.ts`. |
296
+ | П1.3.3 | Префикс задач не меняется: Windows default — `\OpenCode\windows-scheduler\`, профиль — `\OpenCode\windows-scheduler-<profile>\` (`windows.ts`); crontab-блок — `opencode-scheduler:<folder>` (legacy без суффикса читается); launchd label — `com.opencode.scheduler.<name>`. В таблице инвариантов указано, что rename 2.0.0 меняет только npm-имя. Итог: `test-docs` 50 → 60/60. |
297
+
298
+ ### Д2. Извлечение общего ядра — ✅ 17.11.2026 (П2.1.3, П2.2.3, П2.4.2 закрыты в З3.1)
299
+
300
+ | Подзадача | Результат |
301
+ |---|---|
302
+ | П2.1.1 | В `src/index.ts` добавлен `createRuntime(ctxLike)` с типом `RuntimeContextLike` (только `location.directory`): язык из настроек, `initDb()`, `migrateJsonToDb()`, `recoverInterruptedRuns()`, `checkJsonBackups()`, GC артефактов, retention, таймеры автопродолжения и дайджеста, инициализация `LockManager`, catch-up пропущенных cron-запусков, `FileWatchManager`/`GitTriggerManager` + `refreshTriggers()`. Возвращает `SchedulerRuntime { projectDirectory, dispose() }`; `dispose` гасит оба таймера и останавливает watcher/git-менеджеры, не закрывая БД (это делает entrypoint после `waitForIdle`). |
303
+ | П2.1.2 | `setup(ctx)` V2 теперь начинается с `const runtime = await createRuntime(ctx)`, регистрация инструментов/RPC/хуков осталась в `setup`. В общем cleanup вместо ручного `clearInterval` и `fileWatcherManager.stop()` вызывается `runtime.dispose()`. Порядок shutdown не изменён: `shutdownGate.begin()` → dispose регистраций → `closeDashboardServer()` → `waitForIdle()` → `closeDb()`. `test-docs` расширен проверкой «setup стартует через createRuntime» → 61/61. |
304
+ | П2.1.3 | Закрыто в З3.1: `server()` V1 вызывает `createV1Hooks()`, который поднимает `createRuntime({ location: { directory } })`. Регистрация V1 — те же `createToolSpecs`, навешенные на `v1Tool()`. |
305
+ | П2.2.1 | Добавлены экспортируемые `ToolHandlers` и `createToolHandlers(runtime)` — реестр из 26 фактических инструментов (ключ = имя инструмента). Все 26 `execute` в `setup` переведены с прямых имён `*Execute` на `handlers.<name>`; сами обработчики пока остаются модульными, `runtime` зарезервирован под перенос состояния. `test-docs` получил две статические проверки: набор ключей `ToolHandlers` совпадает с именами инструментов, в регистрации не осталось прямых `*Execute` → 63/63. `npm run build`, `test-agent-tools` (23/23), `test-audit` (33/33) — OK. |
306
+ | П2.2.2 | Метаданные всех 26 инструментов вынесены в декларативный `createToolSpecs(runtime)`: `ToolSpec { name, input, description, execute, audit? }`. `setup` теперь содержит один цикл `for (const spec of createToolSpecs(runtime))` и общий `editor.add` с `options: { codemode: true }`; аудит навешивается в цикле через `withAudit`, поэтому правила журнала заданы один раз в спецификации. В `setup` осталось два `editor.add` — цикл инструментов и регистрация скилла. `test-docs` расширен проверкой тонкой обёртки → 64/64; `npm run build`, `test-agent-tools` 23/23, `test-audit` 33/33 — OK. |
307
+ | П2.3.1 | Проверено по исходникам: hook-домены (`ctx.tool.hook`, `ctx.permission.hook`, `ctx.event.subscribe`) в коде отсутствуют. Аудит уже общий — `withAudit` навешивается в `createToolSpecs`; permissions — `resolvePermissions`/`buildOpencodeConfig` в env фонового запуска (`src/core/permissions.ts`); события — `emit_event`, `FileWatchManager` и `GitTriggerManager` из `createRuntime`. В `docs/COMPATIBILITY.md` строка матрицы уточнена («API есть, но плагин его не использует») и добавлен абзац «Хуки не используются осознанно» с причинами и следствием для Д3. `test-docs` расширен двумя защитными проверками (общий код не ссылается на V2-домены; документ фиксирует отказ) → 66/66. |
308
+ | П2.3.2 | Не требуется: V2 hook-домены не используются, отдельный hook-адаптер не нужен. ✅ |
309
+ | П2.3.3 | Не требуется: V1-хуки не используются; паритет линий достигается общими handlers и `createRuntime`, а не строковыми ключами. ✅ |
310
+ | П2.4.1 | В `src/index.ts` добавлен `createShutdownHandler(runtime, registrations, { waitMs })`: `shutdownGate.begin()` → последовательный `dispose()` регистраций (ошибка одной логируется и не мешает остальным) → `runtime.dispose()` → `closeDashboardServer()` → `waitForIdle(15_000)` → `closeDb()`. `setup` V2 теперь возвращает этот обработчик с `rpcRegistration`, `registration` и (если есть) `skillRegistration`; ручной cleanup удалён, `shutdownGate.begin()` встречается в коде один раз. В `docs/COMPATIBILITY.md` добавлен абзац «Единая выгрузка». `test-docs` расширен двумя проверками (порядок шагов, использование обработчика) → 68/68. |
311
+ | П2.4.2 | Закрыто в З3.1: V2 отдаёт `createShutdownHandler(runtime, [rpc, tools, skill])` из `setup()`, V1 — `createShutdownHandler(runtime)` из `dispose` в `Hooks`. Порядок шагов и таймаут общие. |
312
+
313
+ ### Д3. V1-адаптер — ✅ 17.11.2026
314
+
315
+ | Подзадача | Результат |
316
+ |---|---|
317
+ | П3.1.1 | `export default Plugin.define({...})` заменён на `const v2Plugin = Plugin.define({...})` (`src/index.ts`); `setup` не менялся. Инлайн-блок запуска dashboard вынесен из `setup` в общую функцию `startSchedulerDashboard()` (одинаковый вызов `startDashboardServer` для обеих линий). `npm run build` — OK. |
318
+ | П3.1.2 | Добавлены: `toV1ToolResult(result)` — конвертация V2 `Tool.Result` в V1 `ToolResult` (строка как есть; `content`-строка/массив text → `{ output, metadata }`; иначе JSON.stringify); `createV1Hooks(input, options)` — `createRuntime({ location: { directory } })`, цикл по тем же `createToolSpecs` c `withAudit`, инструменты через `v1Tool({ description, args: spec.input.shape, execute })`, dashboard при `startDashboard !== false`, возврат `{ tool, dispose: createShutdownHandler(runtime) }`; `v1Plugin: V1PluginModule = { id, server }`, где `server()` вызывает `createV1Hooks({ directory: input.directory })`. Типы V1 — из запиненного `@opencode-ai/plugin@1.19.5`. |
319
+ | П3.1.3 | Итоговый экспорт — `export default { ...v2Plugin, ...v1Plugin }` (V2 читает `setup`, V1 — `server`, каждая линия игнорирует чужие поля). В `docs/COMPATIBILITY.md` добавлен раздел «Двойной экспорт» со схемой entrypoint'ов и перечнем общего ядра; отдельно зафиксировано, что GUI, RPC и скиллы в V1 не регистрируются. |
320
+ | П3.1.4 | Создан `test-dual-entry.mjs`: изолирует `OPENCODE_SCHEDULER_HOME` во временный каталог до динамического импорта `dist/index.js` (нет побочных эффектов на рабочую БД); проверяет форму экспорта (`id`, `setup`, `server`, арность), `createV1Hooks({ startDashboard: false })` — наличие `tool.schedule_task` (description/args/execute) и `dispose`, все ветки `toV1ToolResult`. Все проверки пройдены; тест подключён в `npm test`. Модульная проверка формы — здесь; реальная загрузка обеими линиями OpenCode — в Д4. `test-docs` расширен четырьмя проверками (константа V2, общее ядро в V1-entrypoint, spread-экспорт, подключение теста) → **72/72**. |
321
+ | П3.2.1 | Маппинг вынесен в экспортируемый `createV1Tools(runtime)`: цикл по тем же `createToolSpecs` (фактически **26** инструментов — в плане и матрице было ошибочно «25»), `withAudit` для правил журнала, `v1Tool({ description, args, execute })`. `createV1Hooks` теперь вызывает `createV1Tools(runtime)`, а не собирает реестр инлайн. Комментарий у `createToolSpecs` обновлён: V1-адаптер уже существует. |
322
+ | П3.2.2 | Добавлен `toV1ToolArgs(spec)`: возвращает `spec.input.shape` (V1 `tool()` ждёт `z.ZodRawShape`, а не `ZodObject`) и бросает явную ошибку, если схема не `z.object(...)`. Схемы собраны корневым `zod@4.6.7`, V1 SDK валидирует их своей копией `zod@4.1.8` — совместимость проверена в `test-dual-entry.mjs` (`z1.object(shape).safeParse`): валидные args проходят, отсутствие обязательного `prompt` отбивается. `test-dual-entry` дополнительно проверяет все 26 инструментов: непустое описание, `execute`-функцию, args — plain-объект без `_def`/`parse`. |
323
+ | П3.2.3 | У V1 `tool()` нет параметра `options` (тип `{ description, args, execute }`), поэтому `codemode: true` в V1 не передаётся: инструменты вызываются обычным способом. Отличие зафиксировано в `docs/COMPATIBILITY.md` (раздел «Инструменты в V1» и строка матрицы), поведение не меняется — обработчики, аудит и результаты общие. `test-docs` расширен двумя проверками: `createV1Tools` использует `createToolSpecs`/`v1Tool`/`toV1ToolArgs` и не передаёт `options`; `toV1ToolArgs` читает `.shape` и падает на другой схеме → **74/74**. |
324
+ | П3.4.1 | Создан `src/tui-v1.tsx` (~330 строк): `tuiV1: TuiPlugin` регистрирует маршрут `scheduler`, слот `sidebar_content`, legacy-команды `api.command.register` и таймер обновления 5 с; данные — те же `getJobsView`/`groupJobsForDisplay`/`nextJobSelection`/`statusIcon`/`formatJobLog` из `src/shared/jobs-view.ts`, действия — через `getSchedulerBackend()` и `getTaskLogs()`. Выбор задачи сохраняется в `api.kv`; выгрузка — `api.lifecycle.onDispose` (clearInterval, unregister маршрута и команд). |
325
+ | П3.4.2 | `src/tui.tsx` теперь экспортирует `v2Tui` и `export default { ...v2Tui, tui: tuiV1 }`: один модуль на обе линии (V2 читает `setup`, V1 — `tui`). В `package.json` добавлен `exports["./tui"] = "./src/tui.tsx"` (по документации OpenCode; раньше subpath отсутствовал, из-за чего V2 TUI не загружался). `src/tui-v1.tsx` исключён из `tsconfig.json`, потому что JSX-типы V1-линии компилируются Bun/OpenCode, а не `tsc`; отдельная проверка `tsc` с `moduleResolution: Bundler` проходила без ошибок. |
326
+ | П3.4.3 | Панель V1 повторяет V2 по смыслу: заголовок, дерево матрицы с отступами, `statusIcon`, пауза, следующий запуск, выбранная строка `›`, клик по строке; диалоги действий и лога — через `api.ui.dialog.replace` (`Dialog` + `DialogSelect`/`DialogAlert`); ошибки действий — toast. Слот V1 не даёт unregister, поэтому это статический снимок на старте (ограничение V1 API); маршрут перерисовывается перерегистрацией после `refresh()`. |
327
+ | П3.4.4 | Статическая проверка: `npm run build` OK, `node test-docs.mjs` — **78/78** (четыре новые проверки: экспорт `v2Tui`, двойной модуль, использование `api.slots`/`api.route`/`api.kv`/`api.lifecycle`, `exports["./tui"]`), `test-dual-entry` — все проверки, `test-jobs-view` — 25/25. Реальная загрузка TUI в OpenCode V1 и V2 — в Д4. |
328
+ | П3.5.1 | Проверено: плагин не читает конфиг OpenCode (`config`-хук не объявлен, ни `plugin`, ни `plugins` в `src/` не разбираются), поэтому ключ выбирает загрузчик линии, а чужое поле не может уронить код пакета. В `docs/COMPATIBILITY.md` строка матрицы теперь «ключ своей линии» и добавлен раздел «Конфигурация по линиям»: V1 — `plugin`, V2 — `plugins`/`opencode plugin add`, оба ключа не нужны. |
329
+ | П3.5.2 | README (en/ru/zh) переписаны в разделе Install: таблица «линия → ключ», отдельный пример V1 (`"plugin": [...]`) и V2 (`"plugins": [...]` + `experimental.schedules: false`), пояснение, что TUI входит в тот же пакет через `exports["./tui"]`. `test-docs` расширен двумя проверками (оба ключа во всех трёх локалях; раздел в COMPATIBILITY и отсутствие старой формулировки) → **80/80**. Д3 закрыта. |
330
+
331
+ ### Д4. Регрессия V2 — ✅ 17.11.2026
332
+
333
+ | Подзадача | Результат |
334
+ |---|---|
335
+ | П4.1.1 | `npm run build` собирает `dist/index.js`; `test-dual-entry` импортирует его в изолированном `OPENCODE_SCHEDULER_HOME` и подтверждает `id`, `setup`, `server`, общий `createV1Hooks` и 26 инструментов с описаниями и схемами. Это модульная проверка формы; фактическую загрузку загрузчиком V2 фиксирует З5.3. |
336
+ | П4.1.2 | `npm run build:gui` — OK (`gui-experimental.cjs`, 374.51 kB, gzip 91.00 kB); `src/gui.tsx` и `src/rpc.ts` в этой задаче не менялись, их entrypoint'ы не затронуты dual export. |
337
+ | П4.2.1 | Полный `npm test` — 62 скрипта, ни одного `FAIL`, все финальные сводки `0 failed`; matrix/DAG/gates/dashboard/notifications, POSIX e2e (пропуск на Windows) и `test-shutdown` отработали штатно. Отдельно после сборки: `test-dual-entry`, `test-agent-tools` 23/23, `test-shutdown` — все проверки. |
338
+ | П4.2.2 | `test-docs` — 80/80; цепочка выросла с 61 до 62 скриптов за счёт `test-dual-entry.mjs`. Попытка smoke-запуска реальными CLI (V2 2.2.3, V1 1.19.6) показала, что `plugin list`/`serve` не доказывают инстанцирование плагина, а `opencode run` требует модель и креды; поэтому реальная загрузка обеими линиями перенесена в З5.2/З5.3 без компромисса с секретами. |
339
+
340
+ ### Д5. Тесты совместимости — ✅ 17.11.2026
341
+
342
+ | Подзадача | Результат |
343
+ |---|---|
344
+ | П5.1.1 | `test-dual-entry.mjs` проверяет default export: `id = "opencode-windows-scheduler"`, `setup` и `server` — функции, у `server` один аргумент. |
345
+ | П5.1.2 | Там же: `createV1Hooks({ directory }, { startDashboard: false })` возвращает `tool` (объект) и `dispose` (функция); V1-интеграция дополнительно вызывает `dispose()` дважды — повторная выгрузка не бросает. |
346
+ | П5.1.3 | Добавлена сверка `Object.keys(hooks.tool)` с `Object.keys(createToolHandlers(null))`: V1 и V2 видят один и тот же набор из 26 имён. `createToolHandlers(null)` безопасен — `runtime` пока не используется. |
347
+ | П5.2.1 | `@opencode-ai/plugin@1.19.5` уже запинен в `devDependencies`; его собственная копия `zod@4.1.8` валидирует схемы из корневого `zod@4.6.7` (проверено в `test-dual-entry`). |
348
+ | П5.2.2 | Создан `test-v1-integration.mjs`: реальный `server({ directory })` на V1-типах, изолированный `OPENCODE_SCHEDULER_HOME`, свободный порт через `OPENCODE_SCHEDULER_PORT`, вызовы `list_tasks`, `get_metrics`, `get_dashboard_info` с `success: true` и проверкой `dashboard.port`. Живой дашборд пользователя больше не переиспользуется. |
349
+ | П5.2.3 | TUI проверяется статически: `test-docs` сверяет `exports["./tui"]`, наличие `sidebar_content`, `api.route.register`, `api.kv`, `api.lifecycle` и `src/tui-v1.tsx`. Живой TUI требует интерактивного OpenCode — оставлен ручным сценарием. |
350
+ | П5.3.1 | V2 smoke — модульная форма (`setup`, 26 инструментов) плюс полный `npm test`; попытка реального CLI описана в Д4 и оставлена ручной. |
351
+ | П5.3.2 | GUI/RPC не менялись; `npm run build:gui` собирает `gui-experimental.cjs` (374.51 kB). `test-docs` продолжает сверять entrypoint'ы. |
352
+ | П5.4.1 | В `.github/workflows/ci.yml` добавлены отдельные job `compat-v1` (V1 SDK 1.19.x: `test-dual-entry`, `test-v1-integration`, `test-docs`) и `compat-v2` (устанавливает `@opencode/plugin@2.3.0` и `@opencode/schema@2.3.0`, гоняет `test-dual-entry`, `test-agent-tools`, `test-audit`). |
353
+ | П5.4.2 | Оба job — `ubuntu-latest`, вне матрицы трёх ОС и без `needs` от неё, поэтому недоступность V1-стенда не блокирует Windows/macOS/Linux. `test-docs` расширен четырьмя проверками (подключение `test-v1-integration`, изолированный порт, сверка имён V1/V2, наличие job'ов) → **84/84**. |
354
+
355
+ ### Д6. Релиз 1.5.6 — в работе (подготовка ✅, публикация ждёт разрешения)
356
+
357
+ | Подзадача | Результат |
358
+ |---|---|
359
+ | П6.1.1 | `package.json` → `1.5.6`; `package-lock.json` версии `:3` и `:9` → `1.5.6`. |
360
+ | П6.1.2 | `CHANGELOG.md`: `## [Unreleased]` → `## [1.5.6] - 2026-11-17`, новый пустой `## [Unreleased]` сверху, `### Added` расширен на 5 пунктов (dual V1/V2, 26 инструментов V1, TUI на обеих линиях + исправленный `exports["./tui"]`, `test-dual-entry`/`test-v1-integration`, CI jobs `compat-v1`/`compat-v2`). |
361
+ | П6.1.3 | `CONTRIBUTING.md:73` — пример тега `v1.5.5` → `v1.5.6`; `docs/CONCEPT.md:223` — «V1 и V2 (текущий): один пакет, dual export, общее ядро»; `docs/COMPATIBILITY.md:12` — «2.3.0 (CI job `compat-v2`)»; README Install уже описывает обе линии (`plugin`/`plugins`). |
362
+ | П6.2.1 | Полный прогон: `npm run build` — OK; `npm run test:parallel` — **63/63**; `npm run test:en` — **63/63**; `npm run test:zh` — **63/63**; `test-docs` — **84/84**. |
363
+ | П6.2.2 | Тег `v1.5.6`, release workflow — не выполняются: ожидают отдельного разрешения на publikation в `main`. |
364
+ | П6.2.3 | Проверка npm и GitHub Release — не выполняется по той же причине. |
365
+
366
+