agent-steward 0.0.4 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (279) hide show
  1. package/CHANGELOG.md +309 -2
  2. package/CROSS_PLATFORM.md +19 -0
  3. package/README.md +55 -8
  4. package/ROADMAP-STRATEGY.md +22 -19
  5. package/ROADMAP.md +230 -159
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +356 -0
  9. package/dist/core/analytics.d.ts +6 -0
  10. package/dist/core/analytics.d.ts.map +1 -1
  11. package/dist/core/analytics.js +20 -3
  12. package/dist/core/audit.d.ts +6 -0
  13. package/dist/core/audit.d.ts.map +1 -1
  14. package/dist/core/audit.js +24 -0
  15. package/dist/core/budget.d.ts +118 -0
  16. package/dist/core/budget.d.ts.map +1 -0
  17. package/dist/core/budget.js +206 -0
  18. package/dist/core/cron-to-schtasks.d.ts.map +1 -1
  19. package/dist/core/cron-to-schtasks.js +38 -0
  20. package/dist/core/dry-run.d.ts +26 -1
  21. package/dist/core/dry-run.d.ts.map +1 -1
  22. package/dist/core/dry-run.js +199 -8
  23. package/dist/core/execution.d.ts +203 -0
  24. package/dist/core/execution.d.ts.map +1 -0
  25. package/dist/core/execution.js +309 -0
  26. package/dist/core/feedback.d.ts +192 -0
  27. package/dist/core/feedback.d.ts.map +1 -0
  28. package/dist/core/feedback.js +426 -0
  29. package/dist/core/gate-integrity.d.ts +71 -0
  30. package/dist/core/gate-integrity.d.ts.map +1 -0
  31. package/dist/core/gate-integrity.js +275 -0
  32. package/dist/core/git-trigger.d.ts.map +1 -1
  33. package/dist/core/git-trigger.js +14 -2
  34. package/dist/core/guard-run.d.ts +4 -0
  35. package/dist/core/guard-run.d.ts.map +1 -0
  36. package/dist/core/guard-run.js +101 -0
  37. package/dist/core/guard.d.ts +52 -0
  38. package/dist/core/guard.d.ts.map +1 -0
  39. package/dist/core/guard.js +362 -0
  40. package/dist/core/local-ai.d.ts.map +1 -1
  41. package/dist/core/local-ai.js +7 -3
  42. package/dist/core/lock.d.ts +41 -0
  43. package/dist/core/lock.d.ts.map +1 -1
  44. package/dist/core/lock.js +141 -29
  45. package/dist/core/matrix.d.ts +8 -0
  46. package/dist/core/matrix.d.ts.map +1 -1
  47. package/dist/core/matrix.js +132 -17
  48. package/dist/core/mission.d.ts +103 -0
  49. package/dist/core/mission.d.ts.map +1 -0
  50. package/dist/core/mission.js +374 -0
  51. package/dist/core/opencode-models.d.ts +2 -2
  52. package/dist/core/opencode-models.d.ts.map +1 -1
  53. package/dist/core/opencode-models.js +28 -21
  54. package/dist/core/opencode-usage.d.ts +35 -0
  55. package/dist/core/opencode-usage.d.ts.map +1 -0
  56. package/dist/core/opencode-usage.js +132 -0
  57. package/dist/core/pipeline-apply.d.ts +38 -0
  58. package/dist/core/pipeline-apply.d.ts.map +1 -0
  59. package/dist/core/pipeline-apply.js +117 -0
  60. package/dist/core/pipeline-io.d.ts +13 -0
  61. package/dist/core/pipeline-io.d.ts.map +1 -0
  62. package/dist/core/pipeline-io.js +78 -0
  63. package/dist/core/pipeline-map.d.ts +52 -0
  64. package/dist/core/pipeline-map.d.ts.map +1 -0
  65. package/dist/core/pipeline-map.js +208 -0
  66. package/dist/core/pipeline-spec.d.ts +109 -0
  67. package/dist/core/pipeline-spec.d.ts.map +1 -0
  68. package/dist/core/pipeline-spec.js +554 -0
  69. package/dist/core/ps-wrapper.d.ts +27 -2
  70. package/dist/core/ps-wrapper.d.ts.map +1 -1
  71. package/dist/core/ps-wrapper.js +424 -65
  72. package/dist/core/record-history.d.ts.map +1 -1
  73. package/dist/core/record-history.js +206 -33
  74. package/dist/core/router/rules.d.ts.map +1 -1
  75. package/dist/core/router/rules.js +6 -0
  76. package/dist/core/run-mode.d.ts +12 -0
  77. package/dist/core/run-mode.d.ts.map +1 -0
  78. package/dist/core/run-mode.js +17 -0
  79. package/dist/core/scheduler/linux.d.ts +8 -1
  80. package/dist/core/scheduler/linux.d.ts.map +1 -1
  81. package/dist/core/scheduler/linux.js +34 -9
  82. package/dist/core/scheduler/logs.d.ts +4 -0
  83. package/dist/core/scheduler/logs.d.ts.map +1 -1
  84. package/dist/core/scheduler/logs.js +25 -1
  85. package/dist/core/scheduler/mac.d.ts +44 -2
  86. package/dist/core/scheduler/mac.d.ts.map +1 -1
  87. package/dist/core/scheduler/mac.js +126 -15
  88. package/dist/core/scheduler/windows.d.ts.map +1 -1
  89. package/dist/core/scheduler/windows.js +15 -12
  90. package/dist/core/secrets.d.ts.map +1 -1
  91. package/dist/core/secrets.js +18 -8
  92. package/dist/core/self-analysis.d.ts +32 -2
  93. package/dist/core/self-analysis.d.ts.map +1 -1
  94. package/dist/core/self-analysis.js +38 -27
  95. package/dist/core/shutdown.d.ts +33 -2
  96. package/dist/core/shutdown.d.ts.map +1 -1
  97. package/dist/core/shutdown.js +58 -2
  98. package/dist/core/structured-log.d.ts +37 -1
  99. package/dist/core/structured-log.d.ts.map +1 -1
  100. package/dist/core/structured-log.js +37 -0
  101. package/dist/core/usage-surface.d.ts +25 -0
  102. package/dist/core/usage-surface.d.ts.map +1 -0
  103. package/dist/core/usage-surface.js +41 -0
  104. package/dist/core/worktree-run.d.ts +4 -0
  105. package/dist/core/worktree-run.d.ts.map +1 -0
  106. package/dist/core/worktree-run.js +164 -0
  107. package/dist/core/worktree.d.ts +115 -0
  108. package/dist/core/worktree.d.ts.map +1 -0
  109. package/dist/core/worktree.js +462 -0
  110. package/dist/core/wrappers/bash.d.ts +19 -0
  111. package/dist/core/wrappers/bash.d.ts.map +1 -1
  112. package/dist/core/wrappers/bash.js +230 -27
  113. package/dist/db/capability-repo.d.ts +43 -2
  114. package/dist/db/capability-repo.d.ts.map +1 -1
  115. package/dist/db/capability-repo.js +96 -11
  116. package/dist/db/history-repo.d.ts +70 -5
  117. package/dist/db/history-repo.d.ts.map +1 -1
  118. package/dist/db/history-repo.js +170 -29
  119. package/dist/db/metrics-repo.d.ts +20 -2
  120. package/dist/db/metrics-repo.d.ts.map +1 -1
  121. package/dist/db/metrics-repo.js +35 -13
  122. package/dist/db/migrate.d.ts.map +1 -1
  123. package/dist/db/migrate.js +37 -17
  124. package/dist/db/recovery.d.ts +3 -1
  125. package/dist/db/recovery.d.ts.map +1 -1
  126. package/dist/db/recovery.js +11 -5
  127. package/dist/db/run-journal.d.ts +33 -5
  128. package/dist/db/run-journal.d.ts.map +1 -1
  129. package/dist/db/run-journal.js +78 -14
  130. package/dist/db/run-resume.d.ts +5 -0
  131. package/dist/db/run-resume.d.ts.map +1 -1
  132. package/dist/db/run-resume.js +9 -2
  133. package/dist/db/runs-repo.d.ts +19 -2
  134. package/dist/db/runs-repo.d.ts.map +1 -1
  135. package/dist/db/runs-repo.js +91 -60
  136. package/dist/db/schema.d.ts +2 -2
  137. package/dist/db/schema.d.ts.map +1 -1
  138. package/dist/db/schema.js +132 -2
  139. package/dist/db/templates-repo.d.ts +2 -2
  140. package/dist/db/templates-repo.d.ts.map +1 -1
  141. package/dist/db/templates-repo.js +5 -3
  142. package/dist/history.d.ts +7 -2
  143. package/dist/history.d.ts.map +1 -1
  144. package/dist/history.js +4 -2
  145. package/dist/hook-output.d.ts +2 -0
  146. package/dist/hook-output.d.ts.map +1 -0
  147. package/dist/hook-output.js +31 -0
  148. package/dist/i18n.d.ts +5 -0
  149. package/dist/i18n.d.ts.map +1 -1
  150. package/dist/i18n.js +11 -4
  151. package/dist/index.d.ts +375 -47
  152. package/dist/index.d.ts.map +1 -1
  153. package/dist/index.js +1344 -192
  154. package/dist/notifications.d.ts +53 -2
  155. package/dist/notifications.d.ts.map +1 -1
  156. package/dist/notifications.js +168 -21
  157. package/dist/profiles.d.ts.map +1 -1
  158. package/dist/profiles.js +82 -10
  159. package/dist/rpc.d.ts +354 -0
  160. package/dist/rpc.d.ts.map +1 -1
  161. package/dist/rpc.js +145 -0
  162. package/dist/server.d.ts +32 -2
  163. package/dist/server.d.ts.map +1 -1
  164. package/dist/server.js +154 -30
  165. package/dist/settings.d.ts +44 -2
  166. package/dist/settings.d.ts.map +1 -1
  167. package/dist/settings.js +85 -3
  168. package/dist/shared/jobs-view.d.ts +1 -1
  169. package/dist/shared/jobs-view.d.ts.map +1 -1
  170. package/dist/shared/jobs-view.js +2 -0
  171. package/dist/task-transfer.d.ts +21 -0
  172. package/dist/task-transfer.d.ts.map +1 -1
  173. package/dist/task-transfer.js +64 -3
  174. package/dist/templates.d.ts +2 -2
  175. package/dist/templates.d.ts.map +1 -1
  176. package/dist/templates.js +3 -3
  177. package/dist/types.d.ts +22 -2
  178. package/dist/types.d.ts.map +1 -1
  179. package/dist/workspaces.d.ts.map +1 -1
  180. package/dist/workspaces.js +34 -11
  181. package/docs/ARCHITECTURE.md +319 -66
  182. package/docs/COMPATIBILITY.md +2 -2
  183. package/docs/CONCEPT.md +18 -4
  184. package/docs/CROSS_PLATFORM.ru.md +20 -0
  185. package/docs/CROSS_PLATFORM.zh.md +18 -0
  186. package/docs/EXECUTION-LOOP.md +28 -10
  187. package/docs/FEATURES.md +129 -7
  188. package/docs/FEATURES.zh.md +97 -6
  189. package/docs/MIGRATION.md +2 -2
  190. package/docs/PIPELINE.md +293 -0
  191. package/docs/QA-A2-GUI-TUI.md +205 -0
  192. package/docs/README.ru.md +43 -4
  193. package/docs/README.zh.md +44 -4
  194. package/docs/SAFETY.md +23 -3
  195. package/gui-experimental.cjs +9 -8
  196. package/locales/en.json +58 -3
  197. package/locales/ru.json +58 -3
  198. package/locales/zh.json +58 -3
  199. package/opencode.pipeline.yaml +35 -0
  200. package/package.json +36 -4
  201. package/scripts/check-eslint-baseline.mjs +139 -0
  202. package/scripts/gen-test-plan-counters.mjs +117 -0
  203. package/scripts/github-ci-fetch.ps1 +37 -0
  204. package/scripts/pl-commit.ps1 +112 -0
  205. package/scripts/qa-a2-commit.ps1 +104 -0
  206. package/scripts/test-home.mjs +107 -0
  207. package/skills/scheduled-job-best-practices/SKILL.md +95 -1
  208. package/skills/scheduled-job-best-practices/references/recipes.md +139 -0
  209. package/src/cli.ts +417 -0
  210. package/src/core/analytics.ts +27 -4
  211. package/src/core/audit.ts +25 -0
  212. package/src/core/budget.ts +340 -0
  213. package/src/core/cron-to-schtasks.ts +42 -0
  214. package/src/core/dry-run.ts +235 -12
  215. package/src/core/execution.ts +538 -0
  216. package/src/core/feedback.ts +582 -0
  217. package/src/core/file-watcher.ts +2 -2
  218. package/src/core/gate-integrity.ts +330 -0
  219. package/src/core/git-trigger.ts +18 -5
  220. package/src/core/guard-run.ts +119 -0
  221. package/src/core/guard.ts +431 -0
  222. package/src/core/local-ai.ts +7 -3
  223. package/src/core/lock.ts +178 -37
  224. package/src/core/matrix.ts +158 -52
  225. package/src/core/mission.ts +531 -0
  226. package/src/core/native-notify.ts +1 -1
  227. package/src/core/opencode-models.ts +30 -21
  228. package/src/core/opencode-usage.ts +182 -0
  229. package/src/core/pipeline-apply.ts +158 -0
  230. package/src/core/pipeline-io.ts +96 -0
  231. package/src/core/pipeline-map.ts +283 -0
  232. package/src/core/pipeline-spec.ts +775 -0
  233. package/src/core/ps-wrapper.ts +435 -66
  234. package/src/core/record-history.ts +258 -81
  235. package/src/core/router/rules.ts +6 -0
  236. package/src/core/run-mode.ts +19 -0
  237. package/src/core/schedule-gate.ts +1 -1
  238. package/src/core/scheduler/at-fallback.ts +1 -1
  239. package/src/core/scheduler/linux.ts +40 -11
  240. package/src/core/scheduler/logs.ts +34 -3
  241. package/src/core/scheduler/mac.ts +174 -14
  242. package/src/core/scheduler/registry.ts +2 -2
  243. package/src/core/scheduler/windows.ts +19 -15
  244. package/src/core/secrets.ts +26 -19
  245. package/src/core/self-analysis.ts +75 -29
  246. package/src/core/shutdown.ts +90 -4
  247. package/src/core/structured-log.ts +89 -5
  248. package/src/core/telegram.ts +2 -2
  249. package/src/core/triage-worker.ts +7 -7
  250. package/src/core/triage.ts +2 -2
  251. package/src/core/usage-surface.ts +70 -0
  252. package/src/core/worktree-run.ts +199 -0
  253. package/src/core/worktree.ts +600 -0
  254. package/src/core/wrappers/bash.ts +248 -26
  255. package/src/db/capability-repo.ts +127 -10
  256. package/src/db/history-repo.ts +281 -40
  257. package/src/db/metrics-repo.ts +40 -13
  258. package/src/db/migrate.ts +57 -32
  259. package/src/db/recovery.ts +12 -5
  260. package/src/db/run-journal.ts +100 -13
  261. package/src/db/run-resume.ts +17 -1
  262. package/src/db/runs-repo.ts +147 -65
  263. package/src/db/schema.ts +134 -2
  264. package/src/db/templates-repo.ts +5 -3
  265. package/src/gui.tsx +438 -18
  266. package/src/history.ts +11 -4
  267. package/src/hook-output.ts +39 -0
  268. package/src/i18n.ts +12 -4
  269. package/src/index.ts +1902 -320
  270. package/src/notifications.ts +227 -47
  271. package/src/profiles.ts +88 -10
  272. package/src/rpc.ts +158 -0
  273. package/src/server.ts +201 -41
  274. package/src/settings.ts +125 -5
  275. package/src/shared/jobs-view.ts +3 -1
  276. package/src/task-transfer.ts +90 -6
  277. package/src/templates.ts +3 -3
  278. package/src/types.ts +23 -2
  279. package/src/workspaces.ts +37 -14
@@ -0,0 +1,340 @@
1
+ /**
2
+ * Бюджеты день/неделя (Экономика v2, E-1.1).
3
+ *
4
+ * Чистые функции без БД, HTTP и ОС: расход считается из уже загруженной
5
+ * истории запусков, лимиты задаются пользователем в settings.json.
6
+ * Fail-open по умолчанию: выключенная группа или нулевой лимит никогда
7
+ * не блокируют запуски — они только перестают проверяться.
8
+ */
9
+ import { recordCost, type AnalyticsRecord } from "./analytics.js";
10
+
11
+ export type BudgetPeriod = "day" | "week";
12
+
13
+ /** Лимиты в USD. 0 означает «без лимита» (fail-open). */
14
+ export interface BudgetSettings {
15
+ /** Включён ли учёт/проверка бюджетов. */
16
+ enabled: boolean;
17
+ /** Лимит на один UTC-день, USD (0 — без лимита). */
18
+ dailyUsd: number;
19
+ /** Лимит на одну UTC-неделю (с понедельника), USD (0 — без лимита). */
20
+ weeklyUsd: number;
21
+ }
22
+
23
+ export const DEFAULT_BUDGET_SETTINGS: BudgetSettings = {
24
+ enabled: false,
25
+ dailyUsd: 0,
26
+ weeklyUsd: 0,
27
+ };
28
+
29
+ export function defaultBudgetSettings(): BudgetSettings {
30
+ return { ...DEFAULT_BUDGET_SETTINGS };
31
+ }
32
+
33
+ /** Учёт одного периода: потрачено, осталось, достигнут ли лимит. */
34
+ export interface BudgetUsage {
35
+ period: BudgetPeriod;
36
+ /** Начало периода в UTC, ISO-строка. */
37
+ periodStart: string;
38
+ /** Конечный лимит, USD (0 — лимит выключен). */
39
+ limitUsd: number;
40
+ /** Потрачено завершёнными запусками в периоде, USD. */
41
+ spentUsd: number;
42
+ /** Сколько запусков попало в период. */
43
+ runs: number;
44
+ /** Остаток; 0, если лимит выключен или уже исчерпан. */
45
+ remainingUsd: number;
46
+ /** Доля расхода от лимита (0, если лимит выключен). Может быть > 1. */
47
+ ratio: number;
48
+ /** Лимит включён и расход достиг/превысил его. */
49
+ exceeded: boolean;
50
+ /**
51
+ * Проверка не активна: группа выключена глобально или лимит равен нулю.
52
+ * По умолчанию true — fail-open.
53
+ */
54
+ disabled: boolean;
55
+ }
56
+
57
+ export interface BudgetReport {
58
+ generatedAt: string;
59
+ enabled: boolean;
60
+ day: BudgetUsage;
61
+ week: BudgetUsage;
62
+ /** Хотя бы один включённый лимит достигнут/превышен. */
63
+ exceeded: boolean;
64
+ }
65
+
66
+ function roundUsd(value: number): number {
67
+ return Math.round(value * 1e6) / 1e6;
68
+ }
69
+
70
+ /** Начало UTC-дня, в котором находится `now`. */
71
+ export function startOfUtcDay(now: Date): Date {
72
+ return new Date(
73
+ Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()),
74
+ );
75
+ }
76
+
77
+ /** Начало UTC-недели (понедельник 00:00), в которой находится `now`. */
78
+ export function startOfUtcWeek(now: Date): Date {
79
+ const day = startOfUtcDay(now);
80
+ const weekday = day.getUTCDay(); // 0 = воскресенье
81
+ const mondayOffset = weekday === 0 ? 6 : weekday - 1;
82
+ return new Date(day.getTime() - mondayOffset * 24 * 60 * 60 * 1000);
83
+ }
84
+
85
+ function periodLimit(settings: BudgetSettings, period: BudgetPeriod): number {
86
+ const raw = period === "day" ? settings.dailyUsd : settings.weeklyUsd;
87
+ const value = Number(raw);
88
+ return Number.isFinite(value) && value > 0 ? value : 0;
89
+ }
90
+
91
+ function computeUsage(
92
+ records: AnalyticsRecord[],
93
+ settings: BudgetSettings,
94
+ period: BudgetPeriod,
95
+ start: Date,
96
+ now: Date,
97
+ ): BudgetUsage {
98
+ const startMs = start.getTime();
99
+ const endMs = now.getTime();
100
+ let spent = 0;
101
+ let runs = 0;
102
+
103
+ for (const record of records) {
104
+ // Незавершённые запуски ещё нельзя оценить — как и в buildAnalytics.
105
+ if (record.status === "running") continue;
106
+ // Расход относится к моменту завершения: запуск, начатый до полуночи,
107
+ // но закончившийся внутри периода, должен попасть именно в этот период.
108
+ // Для старых записей без finishedAt сохраняем прежнюю атрибуцию по startedAt.
109
+ const finishedMs = record.finishedAt
110
+ ? new Date(record.finishedAt).getTime()
111
+ : NaN;
112
+ const startedMs = new Date(record.startedAt).getTime();
113
+ const time = Number.isFinite(finishedMs) ? finishedMs : startedMs;
114
+ if (!Number.isFinite(time) || time < startMs || time > endMs) continue;
115
+ spent += recordCost(record);
116
+ runs += 1;
117
+ }
118
+
119
+ const limitUsd = periodLimit(settings, period);
120
+ const spentUsd = roundUsd(spent);
121
+ const disabled = !settings.enabled || limitUsd <= 0;
122
+ const ratio = limitUsd > 0 ? spentUsd / limitUsd : 0;
123
+ return {
124
+ period,
125
+ periodStart: start.toISOString(),
126
+ limitUsd,
127
+ spentUsd,
128
+ runs,
129
+ remainingUsd: disabled ? 0 : roundUsd(Math.max(0, limitUsd - spentUsd)),
130
+ ratio: disabled ? 0 : Math.round(ratio * 1e6) / 1e6,
131
+ exceeded: !disabled && spentUsd >= limitUsd,
132
+ disabled,
133
+ };
134
+ }
135
+
136
+ /**
137
+ * Считает расход за текущий UTC-день и UTC-неделю (с понедельника).
138
+ * Запуск относится к периоду по времени завершения (`finishedAt`, при
139
+ * отсутствии — `startedAt`); даты вне периода и статус `running` игнорируются.
140
+ */
141
+ export function buildBudgetReport(
142
+ records: AnalyticsRecord[],
143
+ settings: BudgetSettings = DEFAULT_BUDGET_SETTINGS,
144
+ now: Date = new Date(),
145
+ ): BudgetReport {
146
+ const day = computeUsage(records, settings, "day", startOfUtcDay(now), now);
147
+ const week = computeUsage(records, settings, "week", startOfUtcWeek(now), now);
148
+ return {
149
+ generatedAt: now.toISOString(),
150
+ enabled: settings.enabled,
151
+ day,
152
+ week,
153
+ exceeded: day.exceeded || week.exceeded,
154
+ };
155
+ }
156
+
157
+ /** Причина решения гейта запуска. */
158
+ export type BudgetGateReason =
159
+ | "disabled"
160
+ | "within_limit"
161
+ | "day_exceeded"
162
+ | "week_exceeded";
163
+
164
+ /** Решение: можно ли начинать новый запуск. */
165
+ export interface BudgetGateDecision {
166
+ allowed: boolean;
167
+ reason: BudgetGateReason;
168
+ /** Какой лимит сработал (только при exceeded). */
169
+ period?: BudgetPeriod;
170
+ report: BudgetReport;
171
+ }
172
+
173
+ /**
174
+ * E-1.2: авто-пауза при превышении лимита.
175
+ *
176
+ * Fail-open: если группа выключена или оба лимита нулевые, запуски не
177
+ * блокируются. Иначе новый запуск пропускается, как только расход за
178
+ * текущий день/неделю достиг лимита. Дневной лимит проверяется первым.
179
+ */
180
+ export function evaluateBudgetGate(
181
+ records: AnalyticsRecord[],
182
+ settings: BudgetSettings = DEFAULT_BUDGET_SETTINGS,
183
+ now: Date = new Date(),
184
+ ): BudgetGateDecision {
185
+ const report = buildBudgetReport(records, settings, now);
186
+ if (!settings.enabled || (report.day.disabled && report.week.disabled)) {
187
+ return { allowed: true, reason: "disabled", report };
188
+ }
189
+ if (report.day.exceeded) {
190
+ return { allowed: false, reason: "day_exceeded", period: "day", report };
191
+ }
192
+ if (report.week.exceeded) {
193
+ return { allowed: false, reason: "week_exceeded", period: "week", report };
194
+ }
195
+ return { allowed: true, reason: "within_limit", report };
196
+ }
197
+
198
+ /** Человекочитаемая причина пропуска; пустая строка, если запуск разрешён. */
199
+ export function formatBudgetSkipMessage(decision: BudgetGateDecision): string {
200
+ if (decision.allowed) return "";
201
+ const usage =
202
+ decision.period === "week" ? decision.report.week : decision.report.day;
203
+ const label = decision.period === "week" ? "weekly" : "daily";
204
+ return `Budget limit exceeded: ${label} spend $${usage.spentUsd.toFixed(2)} of $${usage.limitUsd.toFixed(2)} — run skipped.`;
205
+ }
206
+
207
+ /**
208
+ * E-1.3: текст алерта о превышении бюджета. Пустая строка, если лимит не
209
+ * превышен. Отличается от сообщения о пропуске запуска (E-1.2) тем, что
210
+ * явно сообщает об остановке всех новых запусков.
211
+ */
212
+ export function formatBudgetAlertMessage(decision: BudgetGateDecision): string {
213
+ if (decision.allowed) return "";
214
+ const usage =
215
+ decision.period === "week" ? decision.report.week : decision.report.day;
216
+ const label = decision.period === "week" ? "Weekly" : "Daily";
217
+ return `⚠️ Agent-steward budget alert: ${label} spend $${usage.spentUsd.toFixed(2)} of $${usage.limitUsd.toFixed(2)} — new runs are paused.`;
218
+ }
219
+
220
+ /**
221
+ * E-2.2: гейт токен-бюджета одной задачи (per-task token budget).
222
+ *
223
+ * Лимит задаётся в определении задачи (`tokenBudget`, токены на один запуск).
224
+ * Если какой-либо завершённый прогон задачи в текущем UTC-дне/неделе превысил
225
+ * лимит, новые запуски пропускаются до начала следующего периода — та же
226
+ * логика, что у глобального бюджетного гейта E-1.2, но в разрезе одной задачи.
227
+ * Fail-open: лимит 0/undefined отключает проверку, запуски не блокируются.
228
+ */
229
+ export type TaskTokenBudgetReason =
230
+ | "no_budget"
231
+ | "within_limit"
232
+ | "day_exceeded"
233
+ | "week_exceeded";
234
+
235
+ export interface TaskTokenBudgetDecision {
236
+ allowed: boolean;
237
+ reason: TaskTokenBudgetReason;
238
+ taskName: string;
239
+ tokenBudget: number;
240
+ /** Максимум токенов за один прогон в сработавшем периоде. */
241
+ maxRunTokens: number;
242
+ period?: BudgetPeriod;
243
+ }
244
+
245
+ function normalizeTokenBudget(value: number | undefined): number {
246
+ const n = Number(value);
247
+ return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
248
+ }
249
+
250
+ function maxRunTokensInWindow(
251
+ records: AnalyticsRecord[],
252
+ taskKey: string,
253
+ startMs: number,
254
+ endMs: number,
255
+ ): number {
256
+ let max = 0;
257
+ for (const record of records) {
258
+ if (record.status === "running") continue;
259
+ if ((record.taskName ?? "").trim().toLowerCase() !== taskKey) continue;
260
+ // Расход относится к моменту завершения (как и в глобальном бюджете):
261
+ // запуск, начатый в прошлом периоде, но закончившийся в текущем, учитывается
262
+ // именно в текущем. Для легаси-записей без finishedAt — по startedAt.
263
+ const finishedMs = record.finishedAt
264
+ ? new Date(record.finishedAt).getTime()
265
+ : NaN;
266
+ const startedMs = new Date(record.startedAt).getTime();
267
+ const time = Number.isFinite(finishedMs) ? finishedMs : startedMs;
268
+ if (!Number.isFinite(time) || time < startMs || time > endMs) continue;
269
+ const tokens = Number(record.tokens);
270
+ if (Number.isFinite(tokens) && tokens > max) max = tokens;
271
+ }
272
+ return max;
273
+ }
274
+
275
+ /**
276
+ * Решение гейта персонального токен-бюджета задачи.
277
+ *
278
+ * Источник данных — уже загруженная история (`getHistoryForBudget`). Как и в
279
+ * аналитике (QA-B.1), превышение считается по одному прогону, а не по сумме за
280
+ * период; дневное окно проверяется первым (как дневной лимит в E-1.2).
281
+ */
282
+ export function evaluateTaskTokenBudgetGate(
283
+ records: AnalyticsRecord[],
284
+ taskName: string,
285
+ tokenBudget: number | undefined,
286
+ now: Date = new Date(),
287
+ ): TaskTokenBudgetDecision {
288
+ const budget = normalizeTokenBudget(tokenBudget);
289
+ const key = (taskName ?? "").trim().toLowerCase();
290
+ const base: TaskTokenBudgetDecision = {
291
+ allowed: true,
292
+ reason: budget > 0 ? "within_limit" : "no_budget",
293
+ taskName,
294
+ tokenBudget: budget,
295
+ maxRunTokens: 0,
296
+ };
297
+ if (!budget || !key) return base;
298
+
299
+ const endMs = now.getTime();
300
+ const dayMax = maxRunTokensInWindow(
301
+ records,
302
+ key,
303
+ startOfUtcDay(now).getTime(),
304
+ endMs,
305
+ );
306
+ if (dayMax > budget) {
307
+ return {
308
+ ...base,
309
+ allowed: false,
310
+ reason: "day_exceeded",
311
+ maxRunTokens: dayMax,
312
+ period: "day",
313
+ };
314
+ }
315
+ const weekMax = maxRunTokensInWindow(
316
+ records,
317
+ key,
318
+ startOfUtcWeek(now).getTime(),
319
+ endMs,
320
+ );
321
+ if (weekMax > budget) {
322
+ return {
323
+ ...base,
324
+ allowed: false,
325
+ reason: "week_exceeded",
326
+ maxRunTokens: weekMax,
327
+ period: "week",
328
+ };
329
+ }
330
+ return { ...base, maxRunTokens: Math.max(dayMax, weekMax) };
331
+ }
332
+
333
+ /** Человекочитаемая причина пропуска; пустая строка, если запуск разрешён. */
334
+ export function formatTaskTokenBudgetSkipMessage(
335
+ decision: TaskTokenBudgetDecision,
336
+ ): string {
337
+ if (decision.allowed) return "";
338
+ const period = decision.period === "week" ? "weekly" : "daily";
339
+ return `Task token budget exceeded: "${decision.taskName}" used ${decision.maxRunTokens} tokens in one run (${period} limit ${decision.tokenBudget}) — run skipped.`;
340
+ }
@@ -14,6 +14,8 @@ const UNSUPPORTED_ERROR =
14
14
  " M * * * * -> HOURLY, ежечасно в MM минут (/st 00:MM)\n" +
15
15
  " M H * * * -> DAILY, ежедневно в HH:MM (/st HH:MM)\n" +
16
16
  " M H * * D -> WEEKLY, по неделям в день D в HH:MM (/d D /st HH:MM)\n" +
17
+ " M H D * * -> MONTHLY, первого числа каждого месяца (/d D /st HH:MM)\n" +
18
+ " M H D M * -> MONTHLY в указанном месяце (/m MONTH), раз в год\n" +
17
19
  "\n" +
18
20
  "Не поддерживаются: диапазоны (1-5), списки (1,2,3), комбинации месяца и дня недели,\n" +
19
21
  "*/N в поле дня месяца или дня недели, а также любые другие сложные выражения.\n" +
@@ -34,6 +36,22 @@ const DAY_OF_WEEK_MAP: Record<string, string> = {
34
36
  "7": "SUN",
35
37
  };
36
38
 
39
+ /** Месяцы для schtasks /m (номер месяца cron 1..12). */
40
+ const MONTH_MAP: Record<string, string> = {
41
+ "1": "JANUARY",
42
+ "2": "FEBRUARY",
43
+ "3": "MARCH",
44
+ "4": "APRIL",
45
+ "5": "MAY",
46
+ "6": "JUNE",
47
+ "7": "JULY",
48
+ "8": "AUGUST",
49
+ "9": "SEPTEMBER",
50
+ "10": "OCTOBER",
51
+ "11": "NOVEMBER",
52
+ "12": "DECEMBER",
53
+ };
54
+
37
55
  /**
38
56
  * Проверяет, является ли строка звездочкой "*".
39
57
  */
@@ -188,6 +206,30 @@ export function convertCronToSchTasks(cron: string): CronConversion {
188
206
  };
189
207
  }
190
208
 
209
+ // --- ПАТТЕРН 5: M H D [*|M] * -> MONTHLY (/d D [/m MONTH] /st HH:MM) ---
210
+ // QV-10: годовое выражение `0 4 1 1 *` раньше не конвертировалось и уходило
211
+ // в минутный опрос ОС. Теперь оно выражается нативно: schtasks MONTHLY с /m
212
+ // фиксирует месяц, а /d — день, поэтому тик один раз в год без пустых опросов.
213
+ const dom = parseIntInRange(dayOfMonth, 1, 31);
214
+ if (m !== undefined && h !== undefined && dom !== undefined && isStar(dayOfWeek)) {
215
+ const startTime = String(h).padStart(2, "0") + ":" + String(m).padStart(2, "0");
216
+ const extraFlags: string[] = ["/d", String(dom)];
217
+ if (!isStar(month)) {
218
+ const monthName = MONTH_MAP[month];
219
+ if (!monthName) {
220
+ throw new Error(
221
+ "Неподдерживаемое поле месяца: " + month + ".\n\n" + UNSUPPORTED_ERROR,
222
+ );
223
+ }
224
+ extraFlags.push("/m", monthName);
225
+ }
226
+ return {
227
+ sc: "MONTHLY",
228
+ extraFlags,
229
+ startTime,
230
+ };
231
+ }
232
+
191
233
  // Ни один поддерживаемый паттерн не совпал.
192
234
  throw new Error(UNSUPPORTED_ERROR);
193
235
  }