agent-steward 0.0.3 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (287) hide show
  1. package/CHANGELOG.md +154 -2
  2. package/CROSS_PLATFORM.md +19 -0
  3. package/README.md +54 -9
  4. package/ROADMAP-STRATEGY.md +23 -20
  5. package/ROADMAP.md +140 -143
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +351 -0
  9. package/dist/core/dlq-api.d.ts +44 -0
  10. package/dist/core/dlq-api.d.ts.map +1 -0
  11. package/dist/core/dlq-api.js +68 -0
  12. package/dist/core/dry-run.d.ts.map +1 -1
  13. package/dist/core/dry-run.js +18 -1
  14. package/dist/core/execution.d.ts +203 -0
  15. package/dist/core/execution.d.ts.map +1 -0
  16. package/dist/core/execution.js +309 -0
  17. package/dist/core/gate-integrity.d.ts +35 -0
  18. package/dist/core/gate-integrity.d.ts.map +1 -0
  19. package/dist/core/gate-integrity.js +132 -0
  20. package/dist/core/git-trigger.d.ts.map +1 -1
  21. package/dist/core/git-trigger.js +14 -2
  22. package/dist/core/guard-run.d.ts +4 -0
  23. package/dist/core/guard-run.d.ts.map +1 -0
  24. package/dist/core/guard-run.js +101 -0
  25. package/dist/core/guard.d.ts +52 -0
  26. package/dist/core/guard.d.ts.map +1 -0
  27. package/dist/core/guard.js +362 -0
  28. package/dist/core/lock.d.ts +61 -4
  29. package/dist/core/lock.d.ts.map +1 -1
  30. package/dist/core/lock.js +213 -26
  31. package/dist/core/matrix.d.ts.map +1 -1
  32. package/dist/core/matrix.js +75 -15
  33. package/dist/core/mission.d.ts +83 -0
  34. package/dist/core/mission.d.ts.map +1 -0
  35. package/dist/core/mission.js +334 -0
  36. package/dist/core/one-shot.d.ts +5 -1
  37. package/dist/core/one-shot.d.ts.map +1 -1
  38. package/dist/core/one-shot.js +33 -8
  39. package/dist/core/opencode-cli.d.ts +28 -0
  40. package/dist/core/opencode-cli.d.ts.map +1 -0
  41. package/dist/core/opencode-cli.js +74 -0
  42. package/dist/core/opencode-models.d.ts +62 -0
  43. package/dist/core/opencode-models.d.ts.map +1 -0
  44. package/dist/core/opencode-models.js +277 -0
  45. package/dist/core/pipeline-apply.d.ts +38 -0
  46. package/dist/core/pipeline-apply.d.ts.map +1 -0
  47. package/dist/core/pipeline-apply.js +117 -0
  48. package/dist/core/pipeline-io.d.ts +13 -0
  49. package/dist/core/pipeline-io.d.ts.map +1 -0
  50. package/dist/core/pipeline-io.js +64 -0
  51. package/dist/core/pipeline-map.d.ts +46 -0
  52. package/dist/core/pipeline-map.d.ts.map +1 -0
  53. package/dist/core/pipeline-map.js +196 -0
  54. package/dist/core/pipeline-spec.d.ts +109 -0
  55. package/dist/core/pipeline-spec.d.ts.map +1 -0
  56. package/dist/core/pipeline-spec.js +554 -0
  57. package/dist/core/ps-wrapper.d.ts +19 -2
  58. package/dist/core/ps-wrapper.d.ts.map +1 -1
  59. package/dist/core/ps-wrapper.js +261 -63
  60. package/dist/core/record-history.d.ts +15 -0
  61. package/dist/core/record-history.d.ts.map +1 -1
  62. package/dist/core/record-history.js +183 -58
  63. package/dist/core/router/dispatch.d.ts +36 -0
  64. package/dist/core/router/dispatch.d.ts.map +1 -0
  65. package/dist/core/router/dispatch.js +59 -0
  66. package/dist/core/router/escalation.d.ts +47 -0
  67. package/dist/core/router/escalation.d.ts.map +1 -0
  68. package/dist/core/router/escalation.js +87 -0
  69. package/dist/core/router/planner.d.ts +53 -0
  70. package/dist/core/router/planner.d.ts.map +1 -0
  71. package/dist/core/router/planner.js +113 -0
  72. package/dist/core/router/rules.d.ts +46 -0
  73. package/dist/core/router/rules.d.ts.map +1 -0
  74. package/dist/core/router/rules.js +91 -0
  75. package/dist/core/run-panel-api.d.ts +94 -0
  76. package/dist/core/run-panel-api.d.ts.map +1 -0
  77. package/dist/core/run-panel-api.js +169 -0
  78. package/dist/core/schedule-gate.js +5 -1
  79. package/dist/core/schedule-v2.d.ts +34 -0
  80. package/dist/core/schedule-v2.d.ts.map +1 -1
  81. package/dist/core/schedule-v2.js +91 -5
  82. package/dist/core/scheduler/at-fallback.d.ts +55 -2
  83. package/dist/core/scheduler/at-fallback.d.ts.map +1 -1
  84. package/dist/core/scheduler/at-fallback.js +135 -5
  85. package/dist/core/scheduler/linux.d.ts +18 -2
  86. package/dist/core/scheduler/linux.d.ts.map +1 -1
  87. package/dist/core/scheduler/linux.js +63 -20
  88. package/dist/core/scheduler/mac.d.ts +44 -2
  89. package/dist/core/scheduler/mac.d.ts.map +1 -1
  90. package/dist/core/scheduler/mac.js +126 -15
  91. package/dist/core/scheduler/posix.d.ts.map +1 -1
  92. package/dist/core/scheduler/posix.js +25 -1
  93. package/dist/core/scheduler/registry.d.ts +11 -0
  94. package/dist/core/scheduler/registry.d.ts.map +1 -1
  95. package/dist/core/scheduler/registry.js +83 -21
  96. package/dist/core/scheduler/run-now.d.ts +16 -0
  97. package/dist/core/scheduler/run-now.d.ts.map +1 -0
  98. package/dist/core/scheduler/run-now.js +28 -0
  99. package/dist/core/scheduler/windows.d.ts.map +1 -1
  100. package/dist/core/scheduler/windows.js +15 -12
  101. package/dist/core/secrets.d.ts.map +1 -1
  102. package/dist/core/secrets.js +125 -28
  103. package/dist/core/session.d.ts.map +1 -1
  104. package/dist/core/session.js +18 -11
  105. package/dist/core/structured-log.d.ts +7 -1
  106. package/dist/core/structured-log.d.ts.map +1 -1
  107. package/dist/core/task-name.d.ts +24 -0
  108. package/dist/core/task-name.d.ts.map +1 -0
  109. package/dist/core/task-name.js +40 -0
  110. package/dist/core/worktree-run.d.ts +4 -0
  111. package/dist/core/worktree-run.d.ts.map +1 -0
  112. package/dist/core/worktree-run.js +164 -0
  113. package/dist/core/worktree.d.ts +115 -0
  114. package/dist/core/worktree.d.ts.map +1 -0
  115. package/dist/core/worktree.js +462 -0
  116. package/dist/core/wrappers/bash.d.ts +17 -0
  117. package/dist/core/wrappers/bash.d.ts.map +1 -1
  118. package/dist/core/wrappers/bash.js +224 -28
  119. package/dist/db/capability-repo.d.ts +124 -0
  120. package/dist/db/capability-repo.d.ts.map +1 -0
  121. package/dist/db/capability-repo.js +267 -0
  122. package/dist/db/history-repo.d.ts +46 -5
  123. package/dist/db/history-repo.d.ts.map +1 -1
  124. package/dist/db/history-repo.js +107 -25
  125. package/dist/db/index.d.ts +4 -0
  126. package/dist/db/index.d.ts.map +1 -1
  127. package/dist/db/index.js +39 -1
  128. package/dist/db/metrics-repo.js +2 -2
  129. package/dist/db/migrate.d.ts.map +1 -1
  130. package/dist/db/migrate.js +3 -1
  131. package/dist/db/recovery.d.ts.map +1 -1
  132. package/dist/db/recovery.js +5 -4
  133. package/dist/db/run-context.d.ts +103 -0
  134. package/dist/db/run-context.d.ts.map +1 -0
  135. package/dist/db/run-context.js +224 -0
  136. package/dist/db/run-dlq.d.ts +100 -0
  137. package/dist/db/run-dlq.d.ts.map +1 -0
  138. package/dist/db/run-dlq.js +191 -0
  139. package/dist/db/run-journal.d.ts +33 -5
  140. package/dist/db/run-journal.d.ts.map +1 -1
  141. package/dist/db/run-journal.js +78 -14
  142. package/dist/db/run-resume.d.ts +10 -2
  143. package/dist/db/run-resume.d.ts.map +1 -1
  144. package/dist/db/run-resume.js +39 -13
  145. package/dist/db/runs-repo.d.ts +32 -7
  146. package/dist/db/runs-repo.d.ts.map +1 -1
  147. package/dist/db/runs-repo.js +50 -11
  148. package/dist/db/schema.d.ts +2 -2
  149. package/dist/db/schema.d.ts.map +1 -1
  150. package/dist/db/schema.js +216 -3
  151. package/dist/db/settings-repo.d.ts +11 -0
  152. package/dist/db/settings-repo.d.ts.map +1 -1
  153. package/dist/db/settings-repo.js +25 -0
  154. package/dist/db/step-idempotency.d.ts +51 -0
  155. package/dist/db/step-idempotency.d.ts.map +1 -0
  156. package/dist/db/step-idempotency.js +136 -0
  157. package/dist/history.d.ts +1 -1
  158. package/dist/history.d.ts.map +1 -1
  159. package/dist/i18n.d.ts +5 -0
  160. package/dist/i18n.d.ts.map +1 -1
  161. package/dist/i18n.js +11 -4
  162. package/dist/index.d.ts +140 -6
  163. package/dist/index.d.ts.map +1 -1
  164. package/dist/index.js +480 -18
  165. package/dist/notifications.d.ts +22 -0
  166. package/dist/notifications.d.ts.map +1 -1
  167. package/dist/notifications.js +36 -8
  168. package/dist/profiles.d.ts.map +1 -1
  169. package/dist/profiles.js +25 -4
  170. package/dist/rpc.d.ts +924 -0
  171. package/dist/rpc.d.ts.map +1 -1
  172. package/dist/rpc.js +352 -0
  173. package/dist/server.d.ts +46 -0
  174. package/dist/server.d.ts.map +1 -1
  175. package/dist/server.js +172 -53
  176. package/dist/settings.d.ts +2 -2
  177. package/dist/settings.d.ts.map +1 -1
  178. package/dist/settings.js +3 -3
  179. package/dist/shared/jobs-view.d.ts +1 -1
  180. package/dist/shared/jobs-view.d.ts.map +1 -1
  181. package/dist/shared/jobs-view.js +2 -0
  182. package/dist/task-transfer.d.ts +16 -0
  183. package/dist/task-transfer.d.ts.map +1 -1
  184. package/dist/task-transfer.js +16 -0
  185. package/dist/types.d.ts.map +1 -1
  186. package/dist/types.js +7 -0
  187. package/dist/workspaces.d.ts +25 -3
  188. package/dist/workspaces.d.ts.map +1 -1
  189. package/dist/workspaces.js +43 -8
  190. package/docs/ARCHITECTURE.md +498 -58
  191. package/docs/COMPATIBILITY.md +2 -2
  192. package/docs/CONCEPT.md +185 -91
  193. package/docs/CROSS_PLATFORM.ru.md +20 -0
  194. package/docs/CROSS_PLATFORM.zh.md +18 -0
  195. package/docs/EXECUTION-LOOP.md +211 -0
  196. package/docs/FEATURES.md +65 -4
  197. package/docs/FEATURES.zh.md +52 -4
  198. package/docs/MIGRATION.md +2 -2
  199. package/docs/PIPELINE.md +293 -0
  200. package/docs/README.ru.md +44 -5
  201. package/docs/README.zh.md +46 -6
  202. package/docs/SAFETY.md +142 -0
  203. package/docs/SAVINGS.md +29 -0
  204. package/docs/SAVINGS.ru.md +29 -0
  205. package/docs/SAVINGS.zh.md +18 -0
  206. package/gui-experimental.cjs +9 -8
  207. package/locales/en.json +84 -1
  208. package/locales/ru.json +84 -1
  209. package/locales/zh.json +84 -1
  210. package/opencode.pipeline.yaml +35 -0
  211. package/package.json +46 -2
  212. package/scripts/audit-bundle.mjs +215 -0
  213. package/scripts/test-home.mjs +83 -0
  214. package/src/cli.ts +412 -0
  215. package/src/core/dlq-api.ts +98 -0
  216. package/src/core/dry-run.ts +27 -3
  217. package/src/core/execution.ts +538 -0
  218. package/src/core/file-watcher.ts +2 -2
  219. package/src/core/gate-integrity.ts +160 -0
  220. package/src/core/git-trigger.ts +18 -5
  221. package/src/core/guard-run.ts +119 -0
  222. package/src/core/guard.ts +431 -0
  223. package/src/core/lock.ts +244 -30
  224. package/src/core/matrix.ts +95 -50
  225. package/src/core/mission.ts +485 -0
  226. package/src/core/native-notify.ts +1 -1
  227. package/src/core/one-shot.ts +36 -8
  228. package/src/core/opencode-cli.ts +103 -0
  229. package/src/core/opencode-models.ts +315 -0
  230. package/src/core/pipeline-apply.ts +158 -0
  231. package/src/core/pipeline-io.ts +79 -0
  232. package/src/core/pipeline-map.ts +264 -0
  233. package/src/core/pipeline-spec.ts +775 -0
  234. package/src/core/ps-wrapper.ts +274 -64
  235. package/src/core/record-history.ts +229 -104
  236. package/src/core/router/dispatch.ts +94 -0
  237. package/src/core/router/escalation.ts +129 -0
  238. package/src/core/router/planner.ts +166 -0
  239. package/src/core/router/rules.ts +115 -0
  240. package/src/core/run-panel-api.ts +262 -0
  241. package/src/core/schedule-gate.ts +7 -3
  242. package/src/core/schedule-v2.ts +114 -5
  243. package/src/core/scheduler/at-fallback.ts +190 -5
  244. package/src/core/scheduler/linux.ts +72 -21
  245. package/src/core/scheduler/logs.ts +2 -2
  246. package/src/core/scheduler/mac.ts +174 -14
  247. package/src/core/scheduler/posix.ts +20 -1
  248. package/src/core/scheduler/registry.ts +107 -26
  249. package/src/core/scheduler/run-now.ts +32 -0
  250. package/src/core/scheduler/windows.ts +19 -15
  251. package/src/core/secrets.ts +131 -31
  252. package/src/core/session.ts +23 -10
  253. package/src/core/structured-log.ts +22 -5
  254. package/src/core/task-name.ts +67 -0
  255. package/src/core/telegram.ts +2 -2
  256. package/src/core/triage-worker.ts +7 -7
  257. package/src/core/triage.ts +2 -2
  258. package/src/core/worktree-run.ts +199 -0
  259. package/src/core/worktree.ts +600 -0
  260. package/src/core/wrappers/bash.ts +239 -27
  261. package/src/db/capability-repo.ts +402 -0
  262. package/src/db/history-repo.ts +151 -22
  263. package/src/db/index.ts +37 -1
  264. package/src/db/metrics-repo.ts +2 -2
  265. package/src/db/migrate.ts +3 -1
  266. package/src/db/recovery.ts +5 -4
  267. package/src/db/run-context.ts +370 -0
  268. package/src/db/run-dlq.ts +310 -0
  269. package/src/db/run-journal.ts +100 -13
  270. package/src/db/run-resume.ts +65 -13
  271. package/src/db/runs-repo.ts +66 -13
  272. package/src/db/schema.ts +218 -3
  273. package/src/db/settings-repo.ts +31 -0
  274. package/src/db/step-idempotency.ts +185 -0
  275. package/src/gui.tsx +692 -13
  276. package/src/history.ts +1 -1
  277. package/src/i18n.ts +12 -4
  278. package/src/index.ts +648 -8
  279. package/src/notifications.ts +38 -8
  280. package/src/profiles.ts +26 -4
  281. package/src/rpc.ts +379 -0
  282. package/src/server.ts +206 -54
  283. package/src/settings.ts +5 -5
  284. package/src/shared/jobs-view.ts +3 -1
  285. package/src/task-transfer.ts +31 -0
  286. package/src/types.ts +9 -0
  287. package/src/workspaces.ts +58 -9
@@ -0,0 +1,310 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { getDb, withTransaction } from "./index.js";
3
+ import {
4
+ getRun,
5
+ getStep,
6
+ reopenRun,
7
+ retryStep,
8
+ startRun,
9
+ type RunRecord,
10
+ type RunStepRecord,
11
+ } from "./runs-repo.js";
12
+
13
+ /**
14
+ * Dead-letter queue для durable DAG (Спринт 36.4).
15
+ *
16
+ * DLQ — это не «ещё одна таблица истории», а рабочая очередь: сюда попадают
17
+ * шаги, которые упали не случайно, а исчерпали попытки (по умолчанию три).
18
+ * Дальше человек либо повторяет шаг вручную, либо осознанно отказывается от
19
+ * него — в обоих случаях запись закрывается и больше не висит в очереди.
20
+ *
21
+ * Запись создаётся идемпотентно: на один шаг может быть только одна открытая
22
+ * запись (`idx_run_dlq_open_unique`), поэтому повторный скан не плодит дубли,
23
+ * а ручной retry не оставляет «фантомную» открытую запись.
24
+ */
25
+
26
+ /** Статусы записи DLQ: open → retried/discarded. */
27
+ export type DlqStatus = "open" | "retried" | "discarded";
28
+
29
+ /** Почему шаг попал в DLQ. */
30
+ export type DlqReason = "attempts-exhausted" | "manual";
31
+
32
+ /** Сколько попыток считается детерминированным падением по умолчанию. */
33
+ export const DEFAULT_DLQ_MIN_ATTEMPTS = 3;
34
+
35
+ export interface DlqEntry {
36
+ id: string;
37
+ runId: string;
38
+ stepName: string;
39
+ status: DlqStatus;
40
+ reason: DlqReason | string | null;
41
+ error: string | null;
42
+ /** Номер попытки на момент постановки в очередь. */
43
+ attempts: number;
44
+ createdAt: string;
45
+ updatedAt: string;
46
+ resolvedAt: string | null;
47
+ /** Что сделали с записью: manual-retry, discarded и т.п. */
48
+ resolution: string | null;
49
+ }
50
+
51
+ export interface EnqueueResult {
52
+ entry: DlqEntry;
53
+ /** false, если открытая запись на этот шаг уже была. */
54
+ created: boolean;
55
+ }
56
+
57
+ export interface ScanOptions {
58
+ /** Ограничить скан одним запуском. */
59
+ runId?: string | null;
60
+ /** Порог попыток; по умолчанию {@link DEFAULT_DLQ_MIN_ATTEMPTS}. */
61
+ minAttempts?: number;
62
+ /** Максимум шагов за один скан. */
63
+ limit?: number;
64
+ }
65
+
66
+ export interface ListDlqOptions {
67
+ /** open (по умолчанию), конкретный статус или все записи. */
68
+ status?: DlqStatus | "all";
69
+ limit?: number;
70
+ }
71
+
72
+ export interface RetryDeadLetterResult {
73
+ entry: DlqEntry;
74
+ step: RunStepRecord;
75
+ run: RunRecord;
76
+ /** true, если запуск был в failed и его пришлось переоткрыть. */
77
+ runReopened: boolean;
78
+ }
79
+
80
+ function nowIso(): string {
81
+ return new Date().toISOString();
82
+ }
83
+
84
+ function normalizeLimit(limit: number | undefined, fallback: number): number {
85
+ const value = Math.floor(limit ?? fallback);
86
+ if (!Number.isFinite(value) || value < 1) return fallback;
87
+ return Math.min(10000, value);
88
+ }
89
+
90
+ function dlqRowToEntry(row: Record<string, unknown>): DlqEntry {
91
+ return {
92
+ id: String(row.id),
93
+ runId: String(row.run_id),
94
+ stepName: String(row.step_name),
95
+ status: String(row.status) as DlqStatus,
96
+ reason: row.reason == null ? null : String(row.reason),
97
+ error: row.error == null ? null : String(row.error),
98
+ attempts: Number(row.attempts) || 0,
99
+ createdAt: String(row.created_at),
100
+ updatedAt: String(row.updated_at),
101
+ resolvedAt: row.resolved_at == null ? null : String(row.resolved_at),
102
+ resolution: row.resolution == null ? null : String(row.resolution),
103
+ };
104
+ }
105
+
106
+ /** Шаг исчерпал попытки и больше не будет повторён автоматически? */
107
+ export function isDeadLetterStep(
108
+ step: Pick<RunStepRecord, "status" | "attempt">,
109
+ minAttempts = DEFAULT_DLQ_MIN_ATTEMPTS,
110
+ ): boolean {
111
+ const threshold = Math.max(1, Math.floor(minAttempts) || DEFAULT_DLQ_MIN_ATTEMPTS);
112
+ return step.status === "failed" && step.attempt >= threshold;
113
+ }
114
+
115
+ /** Открытая запись DLQ на конкретный шаг (или undefined). */
116
+ export function findOpenDeadLetter(runId: string, stepName: string): DlqEntry | undefined {
117
+ const row = getDb()
118
+ .prepare("SELECT * FROM run_dlq WHERE run_id = ? AND step_name = ? AND status = 'open' LIMIT 1")
119
+ .get(runId, stepName);
120
+ return row ? dlqRowToEntry(row) : undefined;
121
+ }
122
+
123
+ /**
124
+ * Ставит шаг в DLQ. Идемпотентно: если открытая запись уже есть, возвращает её
125
+ * с `created: false`. Ошибка шага сохраняется как снимок на момент постановки.
126
+ */
127
+ export function enqueueDeadLetter(
128
+ runId: string,
129
+ stepName: string,
130
+ options: { reason?: DlqReason; error?: string | null; attempts?: number } = {},
131
+ ): EnqueueResult {
132
+ return withTransaction(() => {
133
+ const existing = findOpenDeadLetter(runId, stepName);
134
+ if (existing) return { entry: existing, created: false };
135
+
136
+ const step = getStep(runId, stepName);
137
+ if (!step) {
138
+ throw new Error(`Шаг не найден: ${runId}/${stepName}`);
139
+ }
140
+
141
+ const id = `dlq_${randomUUID()}`;
142
+ const timestamp = nowIso();
143
+ getDb()
144
+ .prepare(
145
+ `INSERT INTO run_dlq
146
+ (id, run_id, step_name, status, reason, error, attempts, created_at, updated_at,
147
+ resolved_at, resolution)
148
+ VALUES (?, ?, ?, 'open', ?, ?, ?, ?, ?, NULL, NULL)`,
149
+ )
150
+ .run(
151
+ id,
152
+ runId,
153
+ stepName,
154
+ options.reason ?? "attempts-exhausted",
155
+ options.error ?? step.error ?? null,
156
+ Math.max(1, Math.floor(options.attempts ?? step.attempt) || 1),
157
+ timestamp,
158
+ timestamp,
159
+ );
160
+
161
+ return { entry: getDeadLetter(id)!, created: true };
162
+ });
163
+ }
164
+
165
+ /**
166
+ * Ищет детерминированно упавшие шаги и ставит их в очередь.
167
+ *
168
+ * Детерминированность здесь прагматичная: шаг в `failed` и `attempt` достиг
169
+ * порога. Автоматические повторы уже не помогут — нужен человек.
170
+ * Возвращает только новые записи, поэтому скан можно вызывать по расписанию.
171
+ */
172
+ export function scanDeadLetters(options: ScanOptions = {}): DlqEntry[] {
173
+ const minAttempts = Math.max(
174
+ 1,
175
+ Math.floor(options.minAttempts ?? DEFAULT_DLQ_MIN_ATTEMPTS) || DEFAULT_DLQ_MIN_ATTEMPTS,
176
+ );
177
+ const limit = normalizeLimit(options.limit, 100);
178
+
179
+ const params: unknown[] = [minAttempts];
180
+ let where = "status = 'failed' AND attempt >= ?";
181
+ if (options.runId) {
182
+ where += " AND run_id = ?";
183
+ params.push(options.runId);
184
+ }
185
+ params.push(limit);
186
+
187
+ const rows = getDb()
188
+ .prepare(
189
+ `SELECT run_id, step_name FROM run_steps WHERE ${where}
190
+ ORDER BY updated_at ASC, rowid ASC LIMIT ?`,
191
+ )
192
+ .all(...params) as { run_id?: unknown; step_name?: unknown }[];
193
+
194
+ const created: DlqEntry[] = [];
195
+ for (const row of rows) {
196
+ const result = enqueueDeadLetter(String(row.run_id), String(row.step_name));
197
+ if (result.created) created.push(result.entry);
198
+ }
199
+ return created;
200
+ }
201
+
202
+ export function getDeadLetter(id: string): DlqEntry | undefined {
203
+ const row = getDb().prepare("SELECT * FROM run_dlq WHERE id = ?").get(id);
204
+ return row ? dlqRowToEntry(row) : undefined;
205
+ }
206
+
207
+ /** Записи очереди, новые сверху. По умолчанию — только открытые. */
208
+ export function listDeadLetters(options: ListDlqOptions = {}): DlqEntry[] {
209
+ const limit = normalizeLimit(options.limit, 100);
210
+ const status = options.status ?? "open";
211
+ if (status === "all") {
212
+ return getDb()
213
+ .prepare("SELECT * FROM run_dlq ORDER BY created_at DESC, rowid DESC LIMIT ?")
214
+ .all(limit)
215
+ .map((row) => dlqRowToEntry(row));
216
+ }
217
+ return getDb()
218
+ .prepare("SELECT * FROM run_dlq WHERE status = ? ORDER BY created_at DESC, rowid DESC LIMIT ?")
219
+ .all(status, limit)
220
+ .map((row) => dlqRowToEntry(row));
221
+ }
222
+
223
+ /** Сколько записей в статусе (по умолчанию открытых). */
224
+ export function countDeadLetters(status: DlqStatus = "open"): number {
225
+ const row = getDb().prepare("SELECT COUNT(*) AS count FROM run_dlq WHERE status = ?").get(status);
226
+ return Number(row?.count) || 0;
227
+ }
228
+
229
+ /**
230
+ * Ручной retry из DLQ.
231
+ *
232
+ * Готовит шаг к повторному выполнению: переоткрывает упавший запуск, переводит
233
+ * шаг в `running` с `attempt + 1` и закрывает запись DLQ как `retried`.
234
+ * Сам обработчик не вызывается — дальше шаг подхватывает `resumeRun`.
235
+ */
236
+ export function retryDeadLetter(
237
+ id: string,
238
+ options: { startedAt?: string } = {},
239
+ ): RetryDeadLetterResult {
240
+ return withTransaction(() => {
241
+ const entry = getDeadLetter(id);
242
+ if (!entry) throw new Error(`Запись DLQ не найдена: ${id}`);
243
+ if (entry.status !== "open") {
244
+ throw new Error(`Запись DLQ уже обработана: ${entry.status}`);
245
+ }
246
+
247
+ const run = getRun(entry.runId);
248
+ if (!run) throw new Error(`Запуск не найден: ${entry.runId}`);
249
+
250
+ const step = getStep(entry.runId, entry.stepName);
251
+ if (!step) throw new Error(`Шаг не найден: ${entry.runId}/${entry.stepName}`);
252
+ if (step.status !== "failed") {
253
+ throw new Error(`Шаг ${entry.stepName} в статусе ${step.status}, повтор невозможен`);
254
+ }
255
+
256
+ let runReopened = false;
257
+ if (run.status === "failed") {
258
+ reopenRun(run.id, options.startedAt);
259
+ runReopened = true;
260
+ } else if (run.status === "pending") {
261
+ startRun(run.id, options.startedAt);
262
+ } else if (run.status !== "running") {
263
+ throw new Error(`Запуск ${run.id} в статусе ${run.status}, повтор невозможен`);
264
+ }
265
+
266
+ retryStep(step.id, options.startedAt);
267
+
268
+ const timestamp = nowIso();
269
+ getDb()
270
+ .prepare(
271
+ `UPDATE run_dlq SET status = 'retried', resolved_at = ?, resolution = 'manual-retry',
272
+ updated_at = ? WHERE id = ?`,
273
+ )
274
+ .run(timestamp, timestamp, id);
275
+
276
+ return {
277
+ entry: getDeadLetter(id)!,
278
+ step: getStep(entry.runId, entry.stepName)!,
279
+ run: getRun(run.id)!,
280
+ runReopened,
281
+ };
282
+ });
283
+ }
284
+
285
+ /** Осознанный отказ: запись закрывается, шаг остаётся failed. */
286
+ export function discardDeadLetter(id: string, resolution = "discarded"): DlqEntry {
287
+ return withTransaction(() => {
288
+ const entry = getDeadLetter(id);
289
+ if (!entry) throw new Error(`Запись DLQ не найдена: ${id}`);
290
+ if (entry.status !== "open") {
291
+ throw new Error(`Запись DLQ уже обработана: ${entry.status}`);
292
+ }
293
+ const timestamp = nowIso();
294
+ getDb()
295
+ .prepare(
296
+ `UPDATE run_dlq SET status = 'discarded', resolved_at = ?, resolution = ?,
297
+ updated_at = ? WHERE id = ?`,
298
+ )
299
+ .run(timestamp, resolution, timestamp, id);
300
+ return getDeadLetter(id)!;
301
+ });
302
+ }
303
+
304
+ /** Готова ли схема к работе с DLQ (таблица из миграции v5). */
305
+ export function isDlqReady(): boolean {
306
+ const row = getDb()
307
+ .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'run_dlq'")
308
+ .get();
309
+ return Boolean(row);
310
+ }
@@ -1,14 +1,17 @@
1
+ import os from "node:os";
1
2
  import { getDb, withTransaction } from "./index.js";
2
3
  import {
3
4
  finishStep,
4
5
  getRun,
5
6
  getStep,
7
+ renewStepLease as renewStepLeaseRow,
6
8
  retryStep,
7
9
  startRun,
8
10
  startStep,
9
11
  type FinishOptions,
10
12
  type RunRecord,
11
13
  type RunStepRecord,
14
+ type StepLease,
12
15
  } from "./runs-repo.js";
13
16
 
14
17
  /**
@@ -23,10 +26,29 @@ import {
23
26
  /** Текст ошибки, которым помечается шаг, прерванный падением процесса. */
24
27
  export const STEP_INTERRUPTED_ERROR = "Прервано падением процесса";
25
28
 
29
+ /**
30
+ * B12: срок lease шага по умолчанию. Живой процесс продлевает lease
31
+ * (heartbeat в `runStepStatefullyAsync` или явный `renewStepLease`), поэтому
32
+ * recovery финализирует шаг только после истечения этого срока.
33
+ */
34
+ export const STEP_LEASE_MS = 60_000;
35
+
36
+ let cachedOwnerId: string | null = null;
37
+
38
+ /** B12: идентификатор текущего процесса — `host:pid:startedAt`. */
39
+ export function getStepOwnerId(): string {
40
+ if (!cachedOwnerId) {
41
+ cachedOwnerId = `${os.hostname()}:${process.pid}:${nowIso()}`;
42
+ }
43
+ return cachedOwnerId;
44
+ }
45
+
26
46
  /** Опции начала попытки. */
27
47
  export interface BeginStepOptions {
28
48
  /** Начать запуск, если он ещё в статусе pending (по умолчанию true). */
29
49
  startRun?: boolean;
50
+ /** B12: срок lease в миллисекундах (по умолчанию {@link STEP_LEASE_MS}). */
51
+ leaseMs?: number;
30
52
  }
31
53
 
32
54
  /** Результат выполнения шага через `runStepStatefully`. */
@@ -68,15 +90,41 @@ export function beginStepAttempt(
68
90
  }
69
91
 
70
92
  const step = requireStep(runId, stepName);
93
+ const lease = buildLease(options.leaseMs);
71
94
  if (step.status === "failed") {
72
- retryStep(step.id);
95
+ retryStep(step.id, undefined, lease);
73
96
  } else {
74
- startStep(step.id);
97
+ startStep(step.id, undefined, lease);
75
98
  }
76
99
 
77
100
  return requireStep(runId, stepName);
78
101
  }
79
102
 
103
+ /**
104
+ * B12: продлевает lease шага текущего процесса.
105
+ *
106
+ * Нужен долгим синхронным шагам: без продления recovery сочтёт шаг
107
+ * осиротевшим после {@link STEP_LEASE_MS}. Возвращает false, если шаг уже
108
+ * не `running`.
109
+ */
110
+ export function renewStepLease(
111
+ runId: string,
112
+ stepName: string,
113
+ leaseMs: number = STEP_LEASE_MS,
114
+ ): boolean {
115
+ const step = requireStep(runId, stepName);
116
+ if (step.status !== "running") return false;
117
+ return renewStepLeaseRow(step.id, buildLease(leaseMs));
118
+ }
119
+
120
+ function buildLease(leaseMs: number = STEP_LEASE_MS): StepLease {
121
+ const duration = Number.isFinite(leaseMs) && leaseMs > 0 ? leaseMs : STEP_LEASE_MS;
122
+ return {
123
+ ownerId: getStepOwnerId(),
124
+ leaseUntil: new Date(Date.now() + duration).toISOString(),
125
+ };
126
+ }
127
+
80
128
  /** Закрывает попытку успехом: running → passed, сохраняет output. */
81
129
  export function recordStepSuccess(
82
130
  runId: string,
@@ -127,39 +175,78 @@ export async function runStepStatefullyAsync<T>(
127
175
  body: () => Promise<T> | T,
128
176
  options: BeginStepOptions = {},
129
177
  ): Promise<StepExecution<T>> {
178
+ const leaseMs = options.leaseMs ?? STEP_LEASE_MS;
130
179
  const attempt = beginStepAttempt(runId, stepName, options).attempt;
180
+ // B12: heartbeat продлевает lease, пока тело шага реально выполняется.
181
+ const timer = setInterval(
182
+ () => {
183
+ try {
184
+ renewStepLease(runId, stepName, leaseMs);
185
+ } catch {
186
+ // Шаг уже финализирован — продлевать нечего.
187
+ }
188
+ },
189
+ Math.max(10, Math.floor(leaseMs / 3)),
190
+ );
191
+ timer.unref?.();
131
192
  let result: T;
132
193
  try {
133
- result = await body();
134
- } catch (err) {
135
- recordStepFailure(runId, stepName, err);
136
- throw err;
194
+ try {
195
+ result = await body();
196
+ } catch (err) {
197
+ recordStepFailure(runId, stepName, err);
198
+ throw err;
199
+ }
200
+ } finally {
201
+ clearInterval(timer);
137
202
  }
138
203
  const step = recordStepSuccess(runId, stepName, result);
139
204
  return { step, result, attempt };
140
205
  }
141
206
 
207
+ export interface RecoverStepsOptions {
208
+ /**
209
+ * B12: текущий момент для проверки lease. По умолчанию now; тесты и
210
+ * отложенный recovery передают «будущее», чтобы lease считался истёкшим.
211
+ */
212
+ now?: string | Date;
213
+ }
214
+
142
215
  /**
143
- * Помечает все зависшие `running`-шаги как failed, сохраняя `attempt`.
216
+ * Помечает осиротевшие `running`-шаги как failed, сохраняя `attempt`.
144
217
  *
145
- * Возвращает обновлённые записи. `attempt` не сбрасывается — следующая попытка
146
- * получит `attempt + 1` через `retryStep`, поэтому номер попытки переживает
147
- * падение процесса и восстановление.
218
+ * B12: шаг финализируется только при отсутствии lease (legacy-строки) или
219
+ * истёкшем `lease_until`. Шаг с живым lease принадлежит работающему процессу
220
+ * и не трогается. Возвращает обновлённые записи.
221
+ *
222
+ * `attempt` не сбрасывается — следующая попытка получит `attempt + 1` через
223
+ * `retryStep`, поэтому номер попытки переживает падение процесса и восстановление.
148
224
  */
149
- export function recoverInterruptedSteps(runId?: string): RunStepRecord[] {
225
+ export function recoverInterruptedSteps(
226
+ runId?: string,
227
+ options: RecoverStepsOptions = {},
228
+ ): RunStepRecord[] {
150
229
  const running = listRunningSteps(runId);
151
230
  if (running.length === 0) return [];
152
231
 
232
+ const nowMs = options.now ? new Date(options.now).getTime() : Date.now();
233
+ const expired = running.filter((step) => {
234
+ if (!step.leaseUntil) return true;
235
+ const until = Date.parse(step.leaseUntil);
236
+ return Number.isNaN(until) || until <= nowMs;
237
+ });
238
+ if (expired.length === 0) return [];
239
+
153
240
  return withTransaction(() => {
154
241
  const timestamp = nowIso();
155
242
  const update = getDb().prepare(
156
243
  `UPDATE run_steps SET status = 'failed', error = ?, finished_at = ?,
157
244
  updated_at = ? WHERE id = ? AND status = 'running'`,
158
245
  );
159
- for (const step of running) {
246
+ for (const step of expired) {
160
247
  update.run(STEP_INTERRUPTED_ERROR, timestamp, timestamp, step.id);
161
248
  }
162
- return running.map((step) => requireStep(step.runId, step.stepName));
249
+ return expired.map((step) => requireStep(step.runId, step.stepName));
163
250
  });
164
251
  }
165
252
 
@@ -8,11 +8,18 @@ import {
8
8
  type RunStepRecord,
9
9
  } from "./runs-repo.js";
10
10
  import {
11
+ listRunningSteps,
11
12
  recoverInterruptedSteps,
12
13
  requireRun,
13
14
  runStepStatefully,
14
15
  runStepStatefullyAsync,
15
16
  } from "./run-journal.js";
17
+ import {
18
+ consumeInjections,
19
+ consumeOrphanInjections,
20
+ pendingInjectionsForStep,
21
+ type StepContext,
22
+ } from "./run-context.js";
16
23
 
17
24
  /**
18
25
  * Resume с середины (Sprint 36.2).
@@ -23,8 +30,8 @@ import {
23
30
  * Уже успешные шаги повторно не запускаются, а `attempt` упавших растёт.
24
31
  */
25
32
 
26
- /** Обработчик тела шага. Получает актуальную запись шага. */
27
- export type StepHandler = (step: RunStepRecord) => unknown;
33
+ /** Обработчик тела шага. Получает актуальную запись шага и контекст паузы. */
34
+ export type StepHandler = (step: RunStepRecord, context: StepContext) => unknown;
28
35
 
29
36
  /** Опции возобновления. */
30
37
  export interface ResumeOptions {
@@ -32,6 +39,11 @@ export interface ResumeOptions {
32
39
  handlers: Record<string, StepHandler>;
33
40
  /** Восстанавливать зависшие `running`-шаги перед продолжением (по умолчанию true). */
34
41
  recover?: boolean;
42
+ /**
43
+ * B12: момент для проверки lease при восстановлении. По умолчанию now.
44
+ * Передавайте будущее время, чтобы считать lease зависшего шага истёкшим.
45
+ */
46
+ recoverNow?: string | Date;
35
47
  /** Останавливаться на первой ошибке (по умолчанию true). */
36
48
  stopOnError?: boolean;
37
49
  }
@@ -48,6 +60,8 @@ export interface ResumeResult {
48
60
  executed: string[];
49
61
  /** Шаги, пропущенные как уже завершённые. */
50
62
  skipped: string[];
63
+ /** Идентификаторы вставок контекста, переданных шагам в этот раз. */
64
+ injected: string[];
51
65
  /** Первый упавший шаг, если цепочка остановилась. */
52
66
  failedStep: string | null;
53
67
  /** Текст ошибки упавшего шага. */
@@ -76,7 +90,17 @@ function prepareResume(runId: string, options: ResumeOptions): ResumePlan {
76
90
  throw new Error(`Запуск отменён, возобновление невозможно: ${runId}`);
77
91
  }
78
92
 
79
- if (options.recover !== false) recoverInterruptedSteps(runId);
93
+ if (options.recover !== false) recoverInterruptedSteps(runId, { now: options.recoverNow });
94
+
95
+ // B12: шаг с живым lease принадлежит работающему процессу. Возобновлять его
96
+ // здесь нельзя — иначе два исполнителя возьмут один шаг.
97
+ const active = listRunningSteps(runId);
98
+ if (active.length > 0) {
99
+ const step = active[0];
100
+ throw new Error(
101
+ `Шаг ${step.stepName} выполняется другим процессом (lease до ${step.leaseUntil ?? "неизвестно"}); возобновление отложено.`,
102
+ );
103
+ }
80
104
 
81
105
  const steps = listRunSteps(runId);
82
106
  const startIndex = steps.findIndex((step) => !isStepDone(step.status));
@@ -89,7 +113,9 @@ function prepareResume(runId: string, options: ResumeOptions): ResumePlan {
89
113
  }
90
114
  }
91
115
  // Упавший запуск открываем заново: шаги можно перезапускать, attempt не сбрасывается.
92
- if (requireRun(runId).status === "failed") reopenRun(runId);
116
+ // Паузу снимаем тем же переходом paused → running (36.7).
117
+ const current = requireRun(runId);
118
+ if (current.status === "failed" || current.status === "paused") reopenRun(runId);
93
119
  }
94
120
 
95
121
  return { steps, startIndex };
@@ -103,7 +129,7 @@ function prepareResume(runId: string, options: ResumeOptions): ResumePlan {
103
129
  export function resumeRunSync(runId: string, options: ResumeOptions): ResumeResult {
104
130
  const { steps, startIndex } = prepareResume(runId, options);
105
131
  if (startIndex === -1) {
106
- return finalize(runId, null, null, [], steps.map((step) => step.stepName));
132
+ return finalize(runId, null, null, [], steps.map((step) => step.stepName), []);
107
133
  }
108
134
 
109
135
  const resumedFrom = steps[startIndex].stepName;
@@ -112,6 +138,7 @@ export function resumeRunSync(runId: string, options: ResumeOptions): ResumeResu
112
138
  .slice(0, startIndex)
113
139
  .filter((step) => isStepDone(step.status))
114
140
  .map((step) => step.stepName);
141
+ const injected: string[] = [];
115
142
  let resumedFromAttempt: number | null = null;
116
143
 
117
144
  for (let index = startIndex; index < steps.length; index += 1) {
@@ -122,18 +149,27 @@ export function resumeRunSync(runId: string, options: ResumeOptions): ResumeResu
122
149
  }
123
150
 
124
151
  executed.push(step.stepName);
152
+ const context = pendingInjectionsForStep(runId, step.stepName);
125
153
  try {
126
154
  const execution = runStepStatefully(runId, step.stepName, () =>
127
- options.handlers[step.stepName](step),
155
+ options.handlers[step.stepName](step, { injections: context }),
128
156
  );
129
157
  if (resumedFromAttempt === null) resumedFromAttempt = execution.attempt;
158
+ if (context.length > 0) {
159
+ consumeInjections(
160
+ context.map((injection) => injection.id),
161
+ step.stepName,
162
+ execution.attempt,
163
+ );
164
+ injected.push(...context.map((injection) => injection.id));
165
+ }
130
166
  } catch {
131
167
  if (options.stopOnError === false) continue;
132
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
168
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
133
169
  }
134
170
  }
135
171
 
136
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
172
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
137
173
  }
138
174
 
139
175
  /** Асинхронный вариант `resumeRunSync` для шагов с I/O. */
@@ -143,7 +179,7 @@ export async function resumeRun(
143
179
  ): Promise<ResumeResult> {
144
180
  const { steps, startIndex } = prepareResume(runId, options);
145
181
  if (startIndex === -1) {
146
- return finalize(runId, null, null, [], steps.map((step) => step.stepName));
182
+ return finalize(runId, null, null, [], steps.map((step) => step.stepName), []);
147
183
  }
148
184
 
149
185
  const resumedFrom = steps[startIndex].stepName;
@@ -152,6 +188,7 @@ export async function resumeRun(
152
188
  .slice(0, startIndex)
153
189
  .filter((step) => isStepDone(step.status))
154
190
  .map((step) => step.stepName);
191
+ const injected: string[] = [];
155
192
  let resumedFromAttempt: number | null = null;
156
193
 
157
194
  for (let index = startIndex; index < steps.length; index += 1) {
@@ -162,18 +199,27 @@ export async function resumeRun(
162
199
  }
163
200
 
164
201
  executed.push(step.stepName);
202
+ const context = pendingInjectionsForStep(runId, step.stepName);
165
203
  try {
166
204
  const execution = await runStepStatefullyAsync(runId, step.stepName, () =>
167
- options.handlers[step.stepName](step),
205
+ options.handlers[step.stepName](step, { injections: context }),
168
206
  );
169
207
  if (resumedFromAttempt === null) resumedFromAttempt = execution.attempt;
208
+ if (context.length > 0) {
209
+ consumeInjections(
210
+ context.map((injection) => injection.id),
211
+ step.stepName,
212
+ execution.attempt,
213
+ );
214
+ injected.push(...context.map((injection) => injection.id));
215
+ }
170
216
  } catch {
171
217
  if (options.stopOnError === false) continue;
172
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
218
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
173
219
  }
174
220
  }
175
221
 
176
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
222
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
177
223
  }
178
224
 
179
225
  /** Закрывает прогон по фактическому состоянию шагов и собирает результат. */
@@ -183,7 +229,11 @@ function finalize(
183
229
  resumedFromAttempt: number | null,
184
230
  executed: string[],
185
231
  skipped: string[],
232
+ injected: string[],
186
233
  ): ResumeResult {
234
+ // Вставки, адресованные уже завершённым шагам, не должны висеть в истории.
235
+ consumeOrphanInjections(runId);
236
+
187
237
  let steps = listRunSteps(runId);
188
238
  const failed = steps.find((step) => step.status === "failed") ?? null;
189
239
  const unfinished = steps.some(
@@ -196,7 +246,8 @@ function finalize(
196
246
  startRun(runId);
197
247
  run = requireRun(runId);
198
248
  }
199
- if (run.status === "running") {
249
+ // Пауза после последнего шага: продолжать нечего, запуск успешен.
250
+ if (run.status === "running" || run.status === "paused") {
200
251
  finishRun(runId, "passed");
201
252
  run = requireRun(runId);
202
253
  }
@@ -214,6 +265,7 @@ function finalize(
214
265
  resumedFromAttempt,
215
266
  executed,
216
267
  skipped,
268
+ injected,
217
269
  failedStep: failed?.stepName ?? null,
218
270
  error: failed?.error ?? null,
219
271
  };