agent-steward 0.0.3 → 0.0.4

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 (171) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +3 -3
  3. package/ROADMAP-STRATEGY.md +9 -9
  4. package/ROADMAP.md +50 -34
  5. package/dist/core/dlq-api.d.ts +44 -0
  6. package/dist/core/dlq-api.d.ts.map +1 -0
  7. package/dist/core/dlq-api.js +68 -0
  8. package/dist/core/dry-run.d.ts.map +1 -1
  9. package/dist/core/dry-run.js +18 -1
  10. package/dist/core/lock.d.ts +20 -4
  11. package/dist/core/lock.d.ts.map +1 -1
  12. package/dist/core/lock.js +97 -22
  13. package/dist/core/one-shot.d.ts +5 -1
  14. package/dist/core/one-shot.d.ts.map +1 -1
  15. package/dist/core/one-shot.js +33 -8
  16. package/dist/core/opencode-cli.d.ts +28 -0
  17. package/dist/core/opencode-cli.d.ts.map +1 -0
  18. package/dist/core/opencode-cli.js +74 -0
  19. package/dist/core/opencode-models.d.ts +62 -0
  20. package/dist/core/opencode-models.d.ts.map +1 -0
  21. package/dist/core/opencode-models.js +277 -0
  22. package/dist/core/ps-wrapper.d.ts +1 -1
  23. package/dist/core/ps-wrapper.d.ts.map +1 -1
  24. package/dist/core/ps-wrapper.js +11 -1
  25. package/dist/core/record-history.d.ts +15 -0
  26. package/dist/core/record-history.d.ts.map +1 -1
  27. package/dist/core/record-history.js +56 -32
  28. package/dist/core/router/dispatch.d.ts +36 -0
  29. package/dist/core/router/dispatch.d.ts.map +1 -0
  30. package/dist/core/router/dispatch.js +59 -0
  31. package/dist/core/router/escalation.d.ts +47 -0
  32. package/dist/core/router/escalation.d.ts.map +1 -0
  33. package/dist/core/router/escalation.js +87 -0
  34. package/dist/core/router/planner.d.ts +53 -0
  35. package/dist/core/router/planner.d.ts.map +1 -0
  36. package/dist/core/router/planner.js +113 -0
  37. package/dist/core/router/rules.d.ts +46 -0
  38. package/dist/core/router/rules.d.ts.map +1 -0
  39. package/dist/core/router/rules.js +85 -0
  40. package/dist/core/run-panel-api.d.ts +94 -0
  41. package/dist/core/run-panel-api.d.ts.map +1 -0
  42. package/dist/core/run-panel-api.js +169 -0
  43. package/dist/core/schedule-gate.js +5 -1
  44. package/dist/core/schedule-v2.d.ts +34 -0
  45. package/dist/core/schedule-v2.d.ts.map +1 -1
  46. package/dist/core/schedule-v2.js +91 -5
  47. package/dist/core/scheduler/at-fallback.d.ts +55 -2
  48. package/dist/core/scheduler/at-fallback.d.ts.map +1 -1
  49. package/dist/core/scheduler/at-fallback.js +135 -5
  50. package/dist/core/scheduler/linux.d.ts +10 -1
  51. package/dist/core/scheduler/linux.d.ts.map +1 -1
  52. package/dist/core/scheduler/linux.js +29 -11
  53. package/dist/core/scheduler/posix.d.ts.map +1 -1
  54. package/dist/core/scheduler/posix.js +25 -1
  55. package/dist/core/scheduler/registry.d.ts +11 -0
  56. package/dist/core/scheduler/registry.d.ts.map +1 -1
  57. package/dist/core/scheduler/registry.js +83 -21
  58. package/dist/core/scheduler/run-now.d.ts +16 -0
  59. package/dist/core/scheduler/run-now.d.ts.map +1 -0
  60. package/dist/core/scheduler/run-now.js +28 -0
  61. package/dist/core/secrets.d.ts.map +1 -1
  62. package/dist/core/secrets.js +125 -28
  63. package/dist/core/session.d.ts.map +1 -1
  64. package/dist/core/session.js +18 -11
  65. package/dist/core/task-name.d.ts +24 -0
  66. package/dist/core/task-name.d.ts.map +1 -0
  67. package/dist/core/task-name.js +40 -0
  68. package/dist/core/wrappers/bash.d.ts.map +1 -1
  69. package/dist/core/wrappers/bash.js +49 -4
  70. package/dist/db/capability-repo.d.ts +83 -0
  71. package/dist/db/capability-repo.d.ts.map +1 -0
  72. package/dist/db/capability-repo.js +182 -0
  73. package/dist/db/history-repo.d.ts +8 -0
  74. package/dist/db/history-repo.d.ts.map +1 -1
  75. package/dist/db/history-repo.js +19 -0
  76. package/dist/db/index.d.ts +4 -0
  77. package/dist/db/index.d.ts.map +1 -1
  78. package/dist/db/index.js +39 -1
  79. package/dist/db/migrate.d.ts.map +1 -1
  80. package/dist/db/migrate.js +3 -1
  81. package/dist/db/run-context.d.ts +103 -0
  82. package/dist/db/run-context.d.ts.map +1 -0
  83. package/dist/db/run-context.js +224 -0
  84. package/dist/db/run-dlq.d.ts +100 -0
  85. package/dist/db/run-dlq.d.ts.map +1 -0
  86. package/dist/db/run-dlq.js +191 -0
  87. package/dist/db/run-resume.d.ts +5 -2
  88. package/dist/db/run-resume.d.ts.map +1 -1
  89. package/dist/db/run-resume.js +30 -11
  90. package/dist/db/runs-repo.d.ts +13 -5
  91. package/dist/db/runs-repo.d.ts.map +1 -1
  92. package/dist/db/runs-repo.js +28 -5
  93. package/dist/db/schema.d.ts +2 -2
  94. package/dist/db/schema.d.ts.map +1 -1
  95. package/dist/db/schema.js +154 -2
  96. package/dist/db/settings-repo.d.ts +11 -0
  97. package/dist/db/settings-repo.d.ts.map +1 -1
  98. package/dist/db/settings-repo.js +25 -0
  99. package/dist/db/step-idempotency.d.ts +51 -0
  100. package/dist/db/step-idempotency.d.ts.map +1 -0
  101. package/dist/db/step-idempotency.js +136 -0
  102. package/dist/index.d.ts +4 -4
  103. package/dist/index.d.ts.map +1 -1
  104. package/dist/index.js +102 -4
  105. package/dist/rpc.d.ts +678 -0
  106. package/dist/rpc.d.ts.map +1 -1
  107. package/dist/rpc.js +235 -0
  108. package/dist/server.d.ts +31 -0
  109. package/dist/server.d.ts.map +1 -1
  110. package/dist/server.js +95 -35
  111. package/dist/types.d.ts.map +1 -1
  112. package/dist/types.js +7 -0
  113. package/dist/workspaces.d.ts +25 -3
  114. package/dist/workspaces.d.ts.map +1 -1
  115. package/dist/workspaces.js +43 -8
  116. package/docs/ARCHITECTURE.md +229 -5
  117. package/docs/CONCEPT.md +171 -91
  118. package/docs/EXECUTION-LOOP.md +196 -0
  119. package/docs/README.ru.md +2 -2
  120. package/docs/README.zh.md +3 -3
  121. package/docs/SAFETY.md +122 -0
  122. package/docs/SAVINGS.md +29 -0
  123. package/docs/SAVINGS.ru.md +29 -0
  124. package/docs/SAVINGS.zh.md +18 -0
  125. package/gui-experimental.cjs +8 -8
  126. package/locales/en.json +67 -0
  127. package/locales/ru.json +67 -0
  128. package/locales/zh.json +67 -0
  129. package/package.json +28 -3
  130. package/scripts/audit-bundle.mjs +215 -0
  131. package/src/core/dlq-api.ts +98 -0
  132. package/src/core/dry-run.ts +25 -1
  133. package/src/core/lock.ts +95 -22
  134. package/src/core/one-shot.ts +36 -8
  135. package/src/core/opencode-cli.ts +103 -0
  136. package/src/core/opencode-models.ts +315 -0
  137. package/src/core/ps-wrapper.ts +11 -1
  138. package/src/core/record-history.ts +75 -37
  139. package/src/core/router/dispatch.ts +94 -0
  140. package/src/core/router/escalation.ts +129 -0
  141. package/src/core/router/planner.ts +166 -0
  142. package/src/core/router/rules.ts +109 -0
  143. package/src/core/run-panel-api.ts +262 -0
  144. package/src/core/schedule-gate.ts +6 -2
  145. package/src/core/schedule-v2.ts +114 -5
  146. package/src/core/scheduler/at-fallback.ts +190 -5
  147. package/src/core/scheduler/linux.ts +32 -10
  148. package/src/core/scheduler/posix.ts +20 -1
  149. package/src/core/scheduler/registry.ts +107 -26
  150. package/src/core/scheduler/run-now.ts +32 -0
  151. package/src/core/secrets.ts +127 -27
  152. package/src/core/session.ts +23 -10
  153. package/src/core/task-name.ts +67 -0
  154. package/src/core/wrappers/bash.ts +49 -4
  155. package/src/db/capability-repo.ts +285 -0
  156. package/src/db/history-repo.ts +22 -0
  157. package/src/db/index.ts +37 -1
  158. package/src/db/migrate.ts +3 -1
  159. package/src/db/run-context.ts +370 -0
  160. package/src/db/run-dlq.ts +310 -0
  161. package/src/db/run-resume.ts +48 -12
  162. package/src/db/runs-repo.ts +30 -7
  163. package/src/db/schema.ts +154 -2
  164. package/src/db/settings-repo.ts +31 -0
  165. package/src/db/step-idempotency.ts +185 -0
  166. package/src/gui.tsx +515 -0
  167. package/src/index.ts +124 -4
  168. package/src/rpc.ts +251 -0
  169. package/src/server.ts +112 -36
  170. package/src/types.ts +9 -0
  171. package/src/workspaces.ts +58 -9
@@ -13,6 +13,12 @@ import {
13
13
  runStepStatefully,
14
14
  runStepStatefullyAsync,
15
15
  } from "./run-journal.js";
16
+ import {
17
+ consumeInjections,
18
+ consumeOrphanInjections,
19
+ pendingInjectionsForStep,
20
+ type StepContext,
21
+ } from "./run-context.js";
16
22
 
17
23
  /**
18
24
  * Resume с середины (Sprint 36.2).
@@ -23,8 +29,8 @@ import {
23
29
  * Уже успешные шаги повторно не запускаются, а `attempt` упавших растёт.
24
30
  */
25
31
 
26
- /** Обработчик тела шага. Получает актуальную запись шага. */
27
- export type StepHandler = (step: RunStepRecord) => unknown;
32
+ /** Обработчик тела шага. Получает актуальную запись шага и контекст паузы. */
33
+ export type StepHandler = (step: RunStepRecord, context: StepContext) => unknown;
28
34
 
29
35
  /** Опции возобновления. */
30
36
  export interface ResumeOptions {
@@ -48,6 +54,8 @@ export interface ResumeResult {
48
54
  executed: string[];
49
55
  /** Шаги, пропущенные как уже завершённые. */
50
56
  skipped: string[];
57
+ /** Идентификаторы вставок контекста, переданных шагам в этот раз. */
58
+ injected: string[];
51
59
  /** Первый упавший шаг, если цепочка остановилась. */
52
60
  failedStep: string | null;
53
61
  /** Текст ошибки упавшего шага. */
@@ -89,7 +97,9 @@ function prepareResume(runId: string, options: ResumeOptions): ResumePlan {
89
97
  }
90
98
  }
91
99
  // Упавший запуск открываем заново: шаги можно перезапускать, attempt не сбрасывается.
92
- if (requireRun(runId).status === "failed") reopenRun(runId);
100
+ // Паузу снимаем тем же переходом paused → running (36.7).
101
+ const current = requireRun(runId);
102
+ if (current.status === "failed" || current.status === "paused") reopenRun(runId);
93
103
  }
94
104
 
95
105
  return { steps, startIndex };
@@ -103,7 +113,7 @@ function prepareResume(runId: string, options: ResumeOptions): ResumePlan {
103
113
  export function resumeRunSync(runId: string, options: ResumeOptions): ResumeResult {
104
114
  const { steps, startIndex } = prepareResume(runId, options);
105
115
  if (startIndex === -1) {
106
- return finalize(runId, null, null, [], steps.map((step) => step.stepName));
116
+ return finalize(runId, null, null, [], steps.map((step) => step.stepName), []);
107
117
  }
108
118
 
109
119
  const resumedFrom = steps[startIndex].stepName;
@@ -112,6 +122,7 @@ export function resumeRunSync(runId: string, options: ResumeOptions): ResumeResu
112
122
  .slice(0, startIndex)
113
123
  .filter((step) => isStepDone(step.status))
114
124
  .map((step) => step.stepName);
125
+ const injected: string[] = [];
115
126
  let resumedFromAttempt: number | null = null;
116
127
 
117
128
  for (let index = startIndex; index < steps.length; index += 1) {
@@ -122,18 +133,27 @@ export function resumeRunSync(runId: string, options: ResumeOptions): ResumeResu
122
133
  }
123
134
 
124
135
  executed.push(step.stepName);
136
+ const context = pendingInjectionsForStep(runId, step.stepName);
125
137
  try {
126
138
  const execution = runStepStatefully(runId, step.stepName, () =>
127
- options.handlers[step.stepName](step),
139
+ options.handlers[step.stepName](step, { injections: context }),
128
140
  );
129
141
  if (resumedFromAttempt === null) resumedFromAttempt = execution.attempt;
142
+ if (context.length > 0) {
143
+ consumeInjections(
144
+ context.map((injection) => injection.id),
145
+ step.stepName,
146
+ execution.attempt,
147
+ );
148
+ injected.push(...context.map((injection) => injection.id));
149
+ }
130
150
  } catch {
131
151
  if (options.stopOnError === false) continue;
132
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
152
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
133
153
  }
134
154
  }
135
155
 
136
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
156
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
137
157
  }
138
158
 
139
159
  /** Асинхронный вариант `resumeRunSync` для шагов с I/O. */
@@ -143,7 +163,7 @@ export async function resumeRun(
143
163
  ): Promise<ResumeResult> {
144
164
  const { steps, startIndex } = prepareResume(runId, options);
145
165
  if (startIndex === -1) {
146
- return finalize(runId, null, null, [], steps.map((step) => step.stepName));
166
+ return finalize(runId, null, null, [], steps.map((step) => step.stepName), []);
147
167
  }
148
168
 
149
169
  const resumedFrom = steps[startIndex].stepName;
@@ -152,6 +172,7 @@ export async function resumeRun(
152
172
  .slice(0, startIndex)
153
173
  .filter((step) => isStepDone(step.status))
154
174
  .map((step) => step.stepName);
175
+ const injected: string[] = [];
155
176
  let resumedFromAttempt: number | null = null;
156
177
 
157
178
  for (let index = startIndex; index < steps.length; index += 1) {
@@ -162,18 +183,27 @@ export async function resumeRun(
162
183
  }
163
184
 
164
185
  executed.push(step.stepName);
186
+ const context = pendingInjectionsForStep(runId, step.stepName);
165
187
  try {
166
188
  const execution = await runStepStatefullyAsync(runId, step.stepName, () =>
167
- options.handlers[step.stepName](step),
189
+ options.handlers[step.stepName](step, { injections: context }),
168
190
  );
169
191
  if (resumedFromAttempt === null) resumedFromAttempt = execution.attempt;
192
+ if (context.length > 0) {
193
+ consumeInjections(
194
+ context.map((injection) => injection.id),
195
+ step.stepName,
196
+ execution.attempt,
197
+ );
198
+ injected.push(...context.map((injection) => injection.id));
199
+ }
170
200
  } catch {
171
201
  if (options.stopOnError === false) continue;
172
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
202
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
173
203
  }
174
204
  }
175
205
 
176
- return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped);
206
+ return finalize(runId, resumedFrom, resumedFromAttempt, executed, skipped, injected);
177
207
  }
178
208
 
179
209
  /** Закрывает прогон по фактическому состоянию шагов и собирает результат. */
@@ -183,7 +213,11 @@ function finalize(
183
213
  resumedFromAttempt: number | null,
184
214
  executed: string[],
185
215
  skipped: string[],
216
+ injected: string[],
186
217
  ): ResumeResult {
218
+ // Вставки, адресованные уже завершённым шагам, не должны висеть в истории.
219
+ consumeOrphanInjections(runId);
220
+
187
221
  let steps = listRunSteps(runId);
188
222
  const failed = steps.find((step) => step.status === "failed") ?? null;
189
223
  const unfinished = steps.some(
@@ -196,7 +230,8 @@ function finalize(
196
230
  startRun(runId);
197
231
  run = requireRun(runId);
198
232
  }
199
- if (run.status === "running") {
233
+ // Пауза после последнего шага: продолжать нечего, запуск успешен.
234
+ if (run.status === "running" || run.status === "paused") {
200
235
  finishRun(runId, "passed");
201
236
  run = requireRun(runId);
202
237
  }
@@ -214,6 +249,7 @@ function finalize(
214
249
  resumedFromAttempt,
215
250
  executed,
216
251
  skipped,
252
+ injected,
217
253
  failedStep: failed?.stepName ?? null,
218
254
  error: failed?.error ?? null,
219
255
  };
@@ -12,8 +12,8 @@ import { getDb, withTransaction } from "./index.js";
12
12
  * пришлось бы переписывать при каждом новом статусе (например, DLQ в 36.4).
13
13
  */
14
14
 
15
- /** Статусы запуска: pending → running → passed/failed; отмена возможна до финала. */
16
- export type RunStatus = "pending" | "running" | "passed" | "failed" | "cancelled";
15
+ /** Статусы запуска: pending → running → passed/failed; paused — пауза с контекстом (36.7). */
16
+ export type RunStatus = "pending" | "running" | "paused" | "passed" | "failed" | "cancelled";
17
17
 
18
18
  /** Статусы шага: pending → running → passed/failed; skipped — осознанный пропуск. */
19
19
  export type StepStatus = "pending" | "running" | "passed" | "failed" | "skipped";
@@ -26,8 +26,12 @@ const TERMINAL_STEP_STATUSES: ReadonlySet<StepStatus> = new Set([
26
26
  ]);
27
27
 
28
28
  const RUN_TRANSITIONS: Record<RunStatus, readonly RunStatus[]> = {
29
- pending: ["running", "cancelled"],
30
- running: ["passed", "failed", "cancelled"],
29
+ // Из pending можно как стартовать, так и сразу поставить на паузу (36.7).
30
+ pending: ["running", "paused", "cancelled"],
31
+ // paused → running — явное возобновление; paused → passed — пауза после
32
+ // последнего шага, когда продолжать уже нечего.
33
+ running: ["paused", "passed", "failed", "cancelled"],
34
+ paused: ["running", "passed", "cancelled"],
31
35
  passed: [],
32
36
  // failed → running — явное возобновление после краха (36.2), только через reopenRun.
33
37
  failed: ["running"],
@@ -315,6 +319,25 @@ export function startRun(id: string, startedAt = nowIso()): boolean {
315
319
  });
316
320
  }
317
321
 
322
+ /**
323
+ * pending/running → paused (Спринт 36.7).
324
+ *
325
+ * Пауза ставится только между шагами: если шаг уже выполняется, вызывающий
326
+ * код должен дождаться его завершения. `finished_at` не заполняется — запуск
327
+ * не завершён, а приостановлен.
328
+ */
329
+ export function pauseRunRecord(id: string, pausedAt = nowIso()): boolean {
330
+ return withTransaction(() => {
331
+ const run = getRun(id);
332
+ if (!run) return false;
333
+ assertTransition("run", run.status, "paused", RUN_TRANSITIONS[run.status]);
334
+ getDb()
335
+ .prepare("UPDATE runs SET status = 'paused', updated_at = ? WHERE id = ?")
336
+ .run(pausedAt, id);
337
+ return true;
338
+ });
339
+ }
340
+
318
341
  /** Завершает запуск (passed/failed/cancelled) и фиксирует finished_at. */
319
342
  export function finishRun(
320
343
  id: string,
@@ -334,10 +357,10 @@ export function finishRun(
334
357
  }
335
358
 
336
359
  /**
337
- * failed → running: возобновление прогона после краха (36.2).
360
+ * failed/paused → running: возобновление прогона после краха или паузы (36.2, 36.7).
338
361
  *
339
- * Разрешено только из failed и не сбрасывает номера попыток шагов —
340
- * они растут через `retryStep` при повторе конкретного шага.
362
+ * Не сбрасывает номера попыток шагов — они растут через `retryStep` при
363
+ * повторе конкретного шага.
341
364
  */
342
365
  export function reopenRun(id: string, startedAt = nowIso()): boolean {
343
366
  return withTransaction(() => {
package/src/db/schema.ts CHANGED
@@ -165,7 +165,67 @@ CREATE TABLE IF NOT EXISTS run_steps (
165
165
 
166
166
  CREATE INDEX IF NOT EXISTS idx_run_steps_run ON run_steps(run_id, created_at);
167
167
  CREATE INDEX IF NOT EXISTS idx_run_steps_status ON run_steps(status);
168
- CREATE INDEX IF NOT EXISTS idx_run_steps_key ON run_steps(run_id, idempotency_key);
168
+
169
+ -- Спринт 36.4 (DLQ): шаги, которые упали детерминированно (исчерпали попытки),
170
+ -- ждут ручного retry или отказа. Открытая запись на шаг может быть только одна,
171
+ -- поэтому ручной retry не создаёт дублей.
172
+ CREATE TABLE IF NOT EXISTS run_dlq (
173
+ id TEXT PRIMARY KEY,
174
+ run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
175
+ step_name TEXT NOT NULL,
176
+ status TEXT NOT NULL,
177
+ reason TEXT,
178
+ error TEXT,
179
+ attempts INTEGER NOT NULL DEFAULT 0,
180
+ created_at TEXT NOT NULL,
181
+ updated_at TEXT NOT NULL,
182
+ resolved_at TEXT,
183
+ resolution TEXT
184
+ );
185
+
186
+ CREATE INDEX IF NOT EXISTS idx_run_dlq_status ON run_dlq(status, created_at DESC);
187
+ CREATE UNIQUE INDEX IF NOT EXISTS idx_run_dlq_open_unique
188
+ ON run_dlq(run_id, step_name) WHERE status = 'open';
189
+
190
+ -- Спринт 36.7 (пауза с инъекцией контекста): комментарий, файл или
191
+ -- структурированный артефакт, оставленный на паузе. Запись адресована
192
+ -- конкретному шагу и передаётся ему при resume ровно один раз.
193
+ CREATE TABLE IF NOT EXISTS run_injections (
194
+ id TEXT PRIMARY KEY,
195
+ run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
196
+ step_name TEXT NOT NULL,
197
+ kind TEXT NOT NULL,
198
+ content TEXT NOT NULL,
199
+ author TEXT NOT NULL,
200
+ metadata_json TEXT,
201
+ created_at TEXT NOT NULL,
202
+ consumed_at TEXT,
203
+ consumed_by_step TEXT,
204
+ consumed_attempt INTEGER
205
+ );
206
+
207
+ CREATE INDEX IF NOT EXISTS idx_run_injections_run
208
+ ON run_injections(run_id, created_at);
209
+ CREATE INDEX IF NOT EXISTS idx_run_injections_pending
210
+ ON run_injections(run_id, step_name) WHERE consumed_at IS NULL;
211
+
212
+ -- Спринт 36.5.b (Capability Map): исходы гейта по типам задач.
213
+ -- Слой 2 роутера читает success_rate и avg_* и выбирает local/cloud/review
214
+ -- без вызова модели. last_10_runs — JSON-массив 1 (гейт пройден) / 0 (провал).
215
+ CREATE TABLE IF NOT EXISTS capability_map (
216
+ task_type TEXT PRIMARY KEY,
217
+ model TEXT NOT NULL,
218
+ runs_total INTEGER NOT NULL DEFAULT 0,
219
+ runs_passed INTEGER NOT NULL DEFAULT 0,
220
+ success_rate REAL NOT NULL DEFAULT 0,
221
+ avg_cost_usd REAL NOT NULL DEFAULT 0,
222
+ avg_time_ms REAL NOT NULL DEFAULT 0,
223
+ last_10_runs TEXT NOT NULL DEFAULT '[]',
224
+ created_at TEXT NOT NULL,
225
+ updated_at TEXT NOT NULL
226
+ );
227
+
228
+ CREATE INDEX IF NOT EXISTS idx_capability_success ON capability_map(success_rate DESC);
169
229
  `;
170
230
 
171
231
  interface SchemaDb {
@@ -181,7 +241,7 @@ interface SchemaDb {
181
241
  * миграций. Увеличивайте при добавлении новой ступени в {@link MIGRATIONS}
182
242
  * и добавляйте соответствующую запись в массив.
183
243
  */
184
- export const SCHEMA_VERSION = 3;
244
+ export const SCHEMA_VERSION = 7;
185
245
 
186
246
  /** Возвращает сохранённую версию схемы (0 у legacy-БД без user_version). */
187
247
  export function getSchemaVersion(db: SchemaDb): number {
@@ -309,6 +369,98 @@ const MIGRATIONS: { to: number; migrate: (db: SchemaDb) => void }[] = [
309
369
  }
310
370
  },
311
371
  },
372
+ {
373
+ // Ступень 4 — Спринт 36.3: ключ идемпотентности уникален в пределах запуска.
374
+ // Дубли (если были) обнуляются, оставляем первый по rowid; затем старый
375
+ // неуникальный индекс заменяется частичным уникальным.
376
+ to: 4,
377
+ migrate(db) {
378
+ db.exec(`UPDATE run_steps SET idempotency_key = NULL
379
+ WHERE idempotency_key IS NOT NULL
380
+ AND rowid NOT IN (
381
+ SELECT MIN(rowid) FROM run_steps
382
+ WHERE idempotency_key IS NOT NULL
383
+ GROUP BY run_id, idempotency_key
384
+ )`);
385
+ db.exec("DROP INDEX IF EXISTS idx_run_steps_key");
386
+ db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_run_steps_key_unique
387
+ ON run_steps(run_id, idempotency_key) WHERE idempotency_key IS NOT NULL`);
388
+ },
389
+ },
390
+ {
391
+ // Ступень 5 — Спринт 36.4: DLQ для детерминированно упавших шагов.
392
+ // Таблица и индексы идемпотентны; уникальный открытый индекс не даёт
393
+ // завести вторую запись на тот же шаг после ручного retry.
394
+ to: 5,
395
+ migrate(db) {
396
+ db.exec(`
397
+ CREATE TABLE IF NOT EXISTS run_dlq (
398
+ id TEXT PRIMARY KEY,
399
+ run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
400
+ step_name TEXT NOT NULL,
401
+ status TEXT NOT NULL,
402
+ reason TEXT,
403
+ error TEXT,
404
+ attempts INTEGER NOT NULL DEFAULT 0,
405
+ created_at TEXT NOT NULL,
406
+ updated_at TEXT NOT NULL,
407
+ resolved_at TEXT,
408
+ resolution TEXT
409
+ );
410
+ CREATE INDEX IF NOT EXISTS idx_run_dlq_status ON run_dlq(status, created_at DESC);
411
+ CREATE UNIQUE INDEX IF NOT EXISTS idx_run_dlq_open_unique
412
+ ON run_dlq(run_id, step_name) WHERE status = 'open';
413
+ `);
414
+ },
415
+ },
416
+ {
417
+ // Ступень 6 — Спринт 36.5.b: Capability Map роутера. Таблица только
418
+ // добавляется, поэтому ступень идемпотентна и безопасна для старых БД.
419
+ to: 6,
420
+ migrate(db) {
421
+ db.exec(`
422
+ CREATE TABLE IF NOT EXISTS capability_map (
423
+ task_type TEXT PRIMARY KEY,
424
+ model TEXT NOT NULL,
425
+ runs_total INTEGER NOT NULL DEFAULT 0,
426
+ runs_passed INTEGER NOT NULL DEFAULT 0,
427
+ success_rate REAL NOT NULL DEFAULT 0,
428
+ avg_cost_usd REAL NOT NULL DEFAULT 0,
429
+ avg_time_ms REAL NOT NULL DEFAULT 0,
430
+ last_10_runs TEXT NOT NULL DEFAULT '[]',
431
+ created_at TEXT NOT NULL,
432
+ updated_at TEXT NOT NULL
433
+ );
434
+ CREATE INDEX IF NOT EXISTS idx_capability_success ON capability_map(success_rate DESC);
435
+ `);
436
+ },
437
+ },
438
+ {
439
+ // Ступень 7 — Спринт 36.7: контекст паузы. Таблица только добавляется,
440
+ // поэтому ступень идемпотентна и безопасна для старых БД.
441
+ to: 7,
442
+ migrate(db) {
443
+ db.exec(`
444
+ CREATE TABLE IF NOT EXISTS run_injections (
445
+ id TEXT PRIMARY KEY,
446
+ run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
447
+ step_name TEXT NOT NULL,
448
+ kind TEXT NOT NULL,
449
+ content TEXT NOT NULL,
450
+ author TEXT NOT NULL,
451
+ metadata_json TEXT,
452
+ created_at TEXT NOT NULL,
453
+ consumed_at TEXT,
454
+ consumed_by_step TEXT,
455
+ consumed_attempt INTEGER
456
+ );
457
+ CREATE INDEX IF NOT EXISTS idx_run_injections_run
458
+ ON run_injections(run_id, created_at);
459
+ CREATE INDEX IF NOT EXISTS idx_run_injections_pending
460
+ ON run_injections(run_id, step_name) WHERE consumed_at IS NULL;
461
+ `);
462
+ },
463
+ },
312
464
  ];
313
465
 
314
466
  /** Имена колонок таблицы (пустой массив, если таблицы нет). */
@@ -29,3 +29,34 @@ export function setSetting(key: string, value: unknown): void {
29
29
  export function deleteSetting(key: string): void {
30
30
  getDb().prepare("DELETE FROM settings WHERE key = ?").run(key);
31
31
  }
32
+
33
+ /**
34
+ * Атомарно уменьшает целочисленный счётчик в settings.
35
+ *
36
+ * P2-30: раньше retry_state был одним JSON-объектом, который читали и
37
+ * перезаписывали целиком разные процессы record-history. При параллельных
38
+ * завершениях задач декременты терялись. Здесь счётчик живёт отдельной
39
+ * строкой, а уменьшение делает один UPDATE — гонки между процессами нет.
40
+ *
41
+ * Возвращает новое значение или null, если счётчик уже исчерпан.
42
+ */
43
+ export function decrementCounterSetting(key: string, initial: number): number | null {
44
+ const db = getDb();
45
+ db.prepare(
46
+ `INSERT INTO settings (key, value_json) VALUES (?, ?)
47
+ ON CONFLICT(key) DO NOTHING`,
48
+ ).run(key, JSON.stringify(Math.max(0, Math.floor(initial))));
49
+
50
+ const row = db
51
+ .prepare(
52
+ `UPDATE settings
53
+ SET value_json = CAST(CAST(value_json AS INTEGER) - 1 AS TEXT)
54
+ WHERE key = ?
55
+ AND CAST(value_json AS INTEGER) > 0
56
+ RETURNING CAST(value_json AS INTEGER) AS value`,
57
+ )
58
+ .get(key);
59
+
60
+ if (!row) return null;
61
+ return Number(row.value);
62
+ }
@@ -0,0 +1,185 @@
1
+ import {
2
+ createStep,
3
+ findStepByIdempotencyKey,
4
+ type RunStepRecord,
5
+ } from "./runs-repo.js";
6
+ import {
7
+ beginStepAttempt,
8
+ recordStepFailure,
9
+ recordStepSuccess,
10
+ } from "./run-journal.js";
11
+
12
+ /**
13
+ * Идемпотентное выполнение шага (Sprint 36.3).
14
+ *
15
+ * Ключ идемпотентности уникален в пределах запуска (частичный UNIQUE-индекс
16
+ * `idx_run_steps_key_unique`). Повторный вызов с тем же ключом не выполняет
17
+ * тело шага второй раз: возвращается сохранённый `output_json` с
18
+ * `replayed: true`. Это защищает от дублей побочных эффектов при ретраях,
19
+ * resume и параллельных вызовах.
20
+ */
21
+
22
+ /** Ключ уже занят другим шагом запуска. */
23
+ export class IdempotencyConflictError extends Error {
24
+ constructor(runId: string, key: string, stepName?: string) {
25
+ super(
26
+ stepName
27
+ ? `Ключ идемпотентности "${key}" в запуске ${runId} уже принадлежит шагу "${stepName}".`
28
+ : `Ключ идемпотентности "${key}" в запуске ${runId} уже используется.`,
29
+ );
30
+ this.name = "IdempotencyConflictError";
31
+ }
32
+ }
33
+
34
+ /** Шаг с этим ключом выполняется прямо сейчас (параллельный дубль). */
35
+ export class StepInFlightError extends Error {
36
+ constructor(runId: string, key: string) {
37
+ super(`Шаг с ключом идемпотентности "${key}" уже выполняется в запуске ${runId}.`);
38
+ this.name = "StepInFlightError";
39
+ }
40
+ }
41
+
42
+ /** Опции идемпотентного шага. */
43
+ export interface StepOnceOptions {
44
+ /** Обязательный ключ; уникален в пределах запуска. */
45
+ idempotencyKey: string;
46
+ /** Начать запуск, если он pending (по умолчанию true). */
47
+ startRun?: boolean;
48
+ }
49
+
50
+ /** Результат `runStepOnce`. */
51
+ export interface StepOnceExecution<T> {
52
+ /** Актуальное состояние шага. */
53
+ step: RunStepRecord;
54
+ /** Результат тела либо сохранённый output при повторе. */
55
+ result: T | null;
56
+ /** true — тело не вызывалось, результат взят из БД. */
57
+ replayed: boolean;
58
+ /** true — тело шага действительно выполнялось. */
59
+ executed: boolean;
60
+ /** Номер попытки, с которым шаг выполнен (или был выполнен раньше). */
61
+ attempt: number;
62
+ }
63
+
64
+ /** Ключи, выполняющиеся в этом процессе: `runId\u0000key`. */
65
+ const inFlight = new Set<string>();
66
+
67
+ function normalizeKey(key: string): string {
68
+ const value = String(key ?? "").trim();
69
+ if (!value) throw new Error("idempotencyKey обязателен для идемпотентного шага.");
70
+ return value;
71
+ }
72
+
73
+ function flightKey(runId: string, key: string): string {
74
+ return `${runId}\u0000${key}`;
75
+ }
76
+
77
+ /**
78
+ * Выполняет шаг ровно один раз на ключ.
79
+ *
80
+ * - новый ключ → шаг создаётся и выполняется;
81
+ * - шаг уже `passed`/`skipped` → тело не вызывается, возвращается кэш;
82
+ * - шаг `failed` → повтор с `attempt + 1` (осознанный ретрай);
83
+ * - шаг `running` или параллельный вызов в этом процессе → `StepInFlightError`;
84
+ * - ключ принадлежит другому шагу → `IdempotencyConflictError`.
85
+ */
86
+ export function runStepOnce<T>(
87
+ runId: string,
88
+ stepName: string,
89
+ options: StepOnceOptions,
90
+ body: () => T,
91
+ ): StepOnceExecution<T> {
92
+ const key = normalizeKey(options.idempotencyKey);
93
+ const flight = flightKey(runId, key);
94
+ if (inFlight.has(flight)) throw new StepInFlightError(runId, key);
95
+ inFlight.add(flight);
96
+
97
+ try {
98
+ const existing = findStepByIdempotencyKey(runId, key);
99
+ if (existing && existing.stepName !== stepName) {
100
+ throw new IdempotencyConflictError(runId, key, existing.stepName);
101
+ }
102
+ if (existing && (existing.status === "passed" || existing.status === "skipped")) {
103
+ return {
104
+ step: existing,
105
+ result: (existing.output as T | null) ?? null,
106
+ replayed: true,
107
+ executed: false,
108
+ attempt: existing.attempt,
109
+ };
110
+ }
111
+ if (existing && existing.status === "running") {
112
+ throw new StepInFlightError(runId, key);
113
+ }
114
+ if (!existing) {
115
+ createStep(runId, { stepName, idempotencyKey: key });
116
+ }
117
+
118
+ const attempt = beginStepAttempt(runId, stepName, {
119
+ startRun: options.startRun,
120
+ }).attempt;
121
+
122
+ let result: T;
123
+ try {
124
+ result = body();
125
+ } catch (err) {
126
+ recordStepFailure(runId, stepName, err);
127
+ throw err;
128
+ }
129
+ const step = recordStepSuccess(runId, stepName, result);
130
+ return { step, result, replayed: false, executed: true, attempt };
131
+ } finally {
132
+ inFlight.delete(flight);
133
+ }
134
+ }
135
+
136
+ /** Асинхронный вариант `runStepOnce` для шагов с I/O. */
137
+ export async function runStepOnceAsync<T>(
138
+ runId: string,
139
+ stepName: string,
140
+ options: StepOnceOptions,
141
+ body: () => Promise<T> | T,
142
+ ): Promise<StepOnceExecution<T>> {
143
+ const key = normalizeKey(options.idempotencyKey);
144
+ const flight = flightKey(runId, key);
145
+ if (inFlight.has(flight)) throw new StepInFlightError(runId, key);
146
+ inFlight.add(flight);
147
+
148
+ try {
149
+ const existing = findStepByIdempotencyKey(runId, key);
150
+ if (existing && existing.stepName !== stepName) {
151
+ throw new IdempotencyConflictError(runId, key, existing.stepName);
152
+ }
153
+ if (existing && (existing.status === "passed" || existing.status === "skipped")) {
154
+ return {
155
+ step: existing,
156
+ result: (existing.output as T | null) ?? null,
157
+ replayed: true,
158
+ executed: false,
159
+ attempt: existing.attempt,
160
+ };
161
+ }
162
+ if (existing && existing.status === "running") {
163
+ throw new StepInFlightError(runId, key);
164
+ }
165
+ if (!existing) {
166
+ createStep(runId, { stepName, idempotencyKey: key });
167
+ }
168
+
169
+ const attempt = beginStepAttempt(runId, stepName, {
170
+ startRun: options.startRun,
171
+ }).attempt;
172
+
173
+ let result: T;
174
+ try {
175
+ result = await body();
176
+ } catch (err) {
177
+ recordStepFailure(runId, stepName, err);
178
+ throw err;
179
+ }
180
+ const step = recordStepSuccess(runId, stepName, result);
181
+ return { step, result, replayed: false, executed: true, attempt };
182
+ } finally {
183
+ inFlight.delete(flight);
184
+ }
185
+ }