devcontour-harness 0.1.0-alpha.30 → 0.1.0-alpha.31

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 (75) hide show
  1. package/README.md +23 -15
  2. package/docs/contracts.md +138 -2
  3. package/docs/release-notes/0.1.0-alpha.31.md +44 -0
  4. package/docs/upgrade.md +44 -0
  5. package/lib/agents/cli-adapter.js +1 -0
  6. package/lib/cli.js +23 -1
  7. package/lib/contracts/cli.d.ts +1077 -4
  8. package/lib/contracts/cli.js +43 -1
  9. package/lib/contracts/diagnosis.d.ts +2 -1
  10. package/lib/contracts/diagnosis.js +1 -0
  11. package/lib/contracts/events.d.ts +414 -5
  12. package/lib/contracts/events.js +46 -1
  13. package/lib/contracts/execution.d.ts +112 -1
  14. package/lib/contracts/execution.js +38 -0
  15. package/lib/contracts/handoff.d.ts +694 -0
  16. package/lib/contracts/handoff.js +291 -0
  17. package/lib/contracts/index.d.ts +1 -0
  18. package/lib/contracts/index.js +1 -0
  19. package/lib/contracts/policy.d.ts +27 -1
  20. package/lib/contracts/policy.js +38 -2
  21. package/lib/contracts/published.d.ts +841 -2
  22. package/lib/contracts/published.js +2 -0
  23. package/lib/contracts/repair-policy.js +5 -0
  24. package/lib/contracts/report.d.ts +2 -0
  25. package/lib/control/harness.d.ts +37 -11
  26. package/lib/control/harness.js +3 -0
  27. package/lib/control/recovery.d.ts +1 -1
  28. package/lib/engine/engine.d.ts +15 -7
  29. package/lib/engine/engine.js +24 -0
  30. package/lib/engine/joint-runner.d.ts +6 -0
  31. package/lib/engine/joint-runner.js +20 -4
  32. package/lib/engine/property-recovery.js +1 -0
  33. package/lib/engine/reuse.js +1 -0
  34. package/lib/engine/runner.d.ts +8 -0
  35. package/lib/engine/runner.js +116 -11
  36. package/lib/engine/stall-sweep.d.ts +137 -0
  37. package/lib/engine/stall-sweep.js +393 -0
  38. package/lib/environment/activity.d.ts +34 -0
  39. package/lib/environment/activity.js +55 -0
  40. package/lib/environment/lifecycle.js +1 -0
  41. package/lib/environment/process.d.ts +7 -1
  42. package/lib/environment/process.js +14 -0
  43. package/lib/environment/redaction.d.ts +2 -0
  44. package/lib/environment/redaction.js +19 -0
  45. package/lib/explain/state.d.ts +1 -1
  46. package/lib/explain/state.js +12 -0
  47. package/lib/handoff/index.d.ts +2 -0
  48. package/lib/handoff/index.js +3 -0
  49. package/lib/handoff/markdown.d.ts +6 -0
  50. package/lib/handoff/markdown.js +153 -0
  51. package/lib/handoff/pack.d.ts +49 -0
  52. package/lib/handoff/pack.js +492 -0
  53. package/lib/index.d.ts +2 -1
  54. package/lib/index.js +1 -0
  55. package/lib/integrations/connector/redact.d.ts +2 -13
  56. package/lib/integrations/connector/redact.js +2 -21
  57. package/lib/projections/attempt.d.ts +28 -0
  58. package/lib/projections/attempt.js +14 -0
  59. package/lib/projections/stop.d.ts +11 -1
  60. package/lib/projections/stop.js +29 -0
  61. package/lib/report/compute.js +1 -0
  62. package/lib/storage/document.d.ts +28 -6
  63. package/lib/storage/sqlite.d.ts +2 -0
  64. package/lib/storage/sqlite.js +9 -1
  65. package/lib/verification/gates-at.d.ts +11 -1
  66. package/lib/verification/gates-at.js +28 -2
  67. package/lib/verification/gates.d.ts +3 -1
  68. package/lib/verification/gates.js +5 -0
  69. package/package.json +1 -1
  70. package/schemas/execution-document.schema.json +68 -0
  71. package/schemas/execution-policy.schema.json +32 -0
  72. package/schemas/handoff-pack.schema.json +1424 -0
  73. package/schemas/run-event.schema.json +360 -0
  74. package/schemas/stop-diagnosis.schema.json +1 -0
  75. package/schemas/value-report.schema.json +1 -0
@@ -2,7 +2,7 @@ import { z } from 'zod';
2
2
  import { API_VERSION } from "./version.js";
3
3
  import { digestSchema, gitShaSchema, idSchema, isoTimeSchema, runtimeNameSchema, } from "./primitives.js";
4
4
  import { sourceRefSchema } from "./work.js";
5
- import { failureKindSchema, workStatusSchema } from "./execution.js";
5
+ import { activitySchema, failureKindSchema, livenessStateSchema, stallActionSchema, workStatusSchema, } from "./execution.js";
6
6
  const sha = gitShaSchema;
7
7
  const text = z.string().max(4000);
8
8
  const runtime = runtimeNameSchema;
@@ -15,6 +15,34 @@ const delivery = {
15
15
  revision: z.string().min(1).max(200),
16
16
  attempts: z.number().int().min(0),
17
17
  };
18
+ /** Переход живости по обходу зависших: общая часть событий попытки и совместной проверки. */
19
+ const liveness = {
20
+ state: livenessStateSchema,
21
+ previous: livenessStateSchema,
22
+ lastMovementAt: isoTimeSchema,
23
+ idleMs: z.number().int().min(0),
24
+ activity: activitySchema.optional(),
25
+ /** ps не дал данных о процессах: оценка только по выводу, не выше `quiet`. */
26
+ cpuUnavailable: z.boolean().optional(),
27
+ action: stallActionSchema.optional(),
28
+ snapshot: z
29
+ .strictObject({
30
+ processes: z
31
+ .array(z.strictObject({
32
+ pid: z.number().int().positive(),
33
+ parentPid: z.number().int().min(0),
34
+ /** Процессорное время; нет — ps его не сообщил. */
35
+ cpuMs: z.number().int().min(0).optional(),
36
+ command: z.string().max(300),
37
+ }))
38
+ .max(20),
39
+ /** ps не дал списка процессов: снимок только из вывода. */
40
+ processesUnavailable: z.boolean().optional(),
41
+ tail: z.string().max(2000),
42
+ artifact: z.string().max(1000).optional(),
43
+ })
44
+ .optional(),
45
+ };
18
46
  /**
19
47
  * Нагрузка каждого типа события — закрытая схема: лишних полей нет, и
20
48
  * поэтому в событие нельзя положить fencing-токен, секрет или произвольный
@@ -90,6 +118,12 @@ export const eventPayloads = {
90
118
  /** Только у `finished`. */
91
119
  outcome: z.enum(['passed', 'failed']).optional(),
92
120
  }),
121
+ /**
122
+ * Обход controller сменил живость исполняющейся попытки (только переходы).
123
+ * У `stalled` — снимок: процессы исполняющихся команд и хвост их вывода
124
+ * (замаскированные), и что controller сделал (`action`).
125
+ */
126
+ 'attempt.liveness': z.strictObject(liveness),
93
127
  'attempt.failed': z.strictObject({
94
128
  failureKind: failureKindSchema,
95
129
  message: text,
@@ -150,6 +184,15 @@ export const eventPayloads = {
150
184
  workIds: z.array(idSchema).max(500),
151
185
  policyDigest: digestSchema,
152
186
  }),
187
+ /**
188
+ * Обход зависших совместной проверки сменил её живость (только переходы);
189
+ * нагрузка — как у `attempt.liveness`. При `report` это единственный след
190
+ * зависания: записи попытки у проверки нет.
191
+ */
192
+ 'joint.liveness': z.strictObject({
193
+ verificationId: z.string().min(1).max(200),
194
+ ...liveness,
195
+ }),
153
196
  /** Совместная проверка закончилась: `passed` — только с manifest. */
154
197
  'joint.finished': z.strictObject({
155
198
  verificationId: z.string().min(1).max(200),
@@ -250,6 +293,7 @@ export const transactionKinds = [
250
293
  'run.model',
251
294
  'run.timing.started',
252
295
  'run.timing.finished',
296
+ 'run.liveness',
253
297
  'evidence.recorded',
254
298
  'reproduction.recorded',
255
299
  'findings.recorded',
@@ -287,6 +331,7 @@ export const transactionKinds = [
287
331
  'workspace.evidence',
288
332
  'workspace.verified',
289
333
  'workspace.failed',
334
+ 'workspace.liveness',
290
335
  /**
291
336
  * Сдвиг ref базы операцией внутри транзакции проверки её владения: только
292
337
  * проверка и синхронный `git update-ref`, записей и событий нет.
@@ -24,7 +24,7 @@ export declare const workStatusSchema: z.ZodEnum<{
24
24
  done: "done";
25
25
  }>;
26
26
  export type WorkStatus = (typeof workStatuses)[number];
27
- export declare const failureKinds: readonly ["provider-auth", "environment", "timeout", "stale-base", "empty-result", "unfinished", "scope-violation", "gate", "review", "review-protocol", "merge", "cancelled", "budget", "needs-lead", "unknown"];
27
+ export declare const failureKinds: readonly ["provider-auth", "environment", "timeout", "stalled", "stale-base", "empty-result", "unfinished", "scope-violation", "gate", "review", "review-protocol", "merge", "cancelled", "budget", "needs-lead", "unknown"];
28
28
  export declare const failureKindSchema: z.ZodEnum<{
29
29
  gate: "gate";
30
30
  unknown: "unknown";
@@ -33,6 +33,7 @@ export declare const failureKindSchema: z.ZodEnum<{
33
33
  environment: "environment";
34
34
  timeout: "timeout";
35
35
  "provider-auth": "provider-auth";
36
+ stalled: "stalled";
36
37
  "stale-base": "stale-base";
37
38
  "empty-result": "empty-result";
38
39
  unfinished: "unfinished";
@@ -43,6 +44,61 @@ export declare const failureKindSchema: z.ZodEnum<{
43
44
  "needs-lead": "needs-lead";
44
45
  }>;
45
46
  export type FailureKind = (typeof failureKinds)[number];
47
+ /**
48
+ * Живость исполняющейся попытки по периодическому обходу controller
49
+ * (`stallSweep` политики): `active` — движение было недавно, `quiet` — нет
50
+ * движения дольше `quietMs`, `stalled` — дольше `stalledMs`. Движение —
51
+ * вывод процесса, начало или конец его команды, граница стадии
52
+ * (`attempt.stage`), заметный расход процессора деревом процессов.
53
+ */
54
+ export declare const livenessStates: readonly ["active", "quiet", "stalled"];
55
+ export declare const livenessStateSchema: z.ZodEnum<{
56
+ active: "active";
57
+ stalled: "stalled";
58
+ quiet: "quiet";
59
+ }>;
60
+ export type LivenessState = (typeof livenessStates)[number];
61
+ /** Что исполняется: вызов агента, gate, шаг среды или прочая команда попытки. */
62
+ export declare const activitySchema: z.ZodObject<{
63
+ kind: z.ZodEnum<{
64
+ gate: "gate";
65
+ command: "command";
66
+ agent: "agent";
67
+ step: "step";
68
+ }>;
69
+ label: z.ZodString;
70
+ }, z.core.$strict>;
71
+ export type Activity = z.infer<typeof activitySchema>;
72
+ /** Действие controller на `stalled`: остановить процесс или только сообщить. */
73
+ export declare const stallActionSchema: z.ZodEnum<{
74
+ report: "report";
75
+ stop: "stop";
76
+ }>;
77
+ /** Последнее состояние живости попытки; пишется только на переходах. */
78
+ export declare const attemptLivenessSchema: z.ZodObject<{
79
+ state: z.ZodEnum<{
80
+ active: "active";
81
+ stalled: "stalled";
82
+ quiet: "quiet";
83
+ }>;
84
+ at: z.ZodISODateTime;
85
+ lastMovementAt: z.ZodISODateTime;
86
+ activity: z.ZodOptional<z.ZodObject<{
87
+ kind: z.ZodEnum<{
88
+ gate: "gate";
89
+ command: "command";
90
+ agent: "agent";
91
+ step: "step";
92
+ }>;
93
+ label: z.ZodString;
94
+ }, z.core.$strict>>;
95
+ action: z.ZodOptional<z.ZodEnum<{
96
+ report: "report";
97
+ stop: "stop";
98
+ }>>;
99
+ artifact: z.ZodOptional<z.ZodString>;
100
+ }, z.core.$strict>;
101
+ export type AttemptLiveness = z.infer<typeof attemptLivenessSchema>;
46
102
  /** Техническое согласование, привязанное к digest проверенного предложения. */
47
103
  export declare const technicalApprovalSchema: z.ZodObject<{
48
104
  actor: z.ZodEnum<{
@@ -601,6 +657,7 @@ export declare const continuationSchema: z.ZodObject<{
601
657
  environment: "environment";
602
658
  timeout: "timeout";
603
659
  "provider-auth": "provider-auth";
660
+ stalled: "stalled";
604
661
  "stale-base": "stale-base";
605
662
  "empty-result": "empty-result";
606
663
  unfinished: "unfinished";
@@ -686,6 +743,7 @@ export declare const attemptStateSchema: z.ZodObject<{
686
743
  environment: "environment";
687
744
  timeout: "timeout";
688
745
  "provider-auth": "provider-auth";
746
+ stalled: "stalled";
689
747
  "stale-base": "stale-base";
690
748
  "empty-result": "empty-result";
691
749
  unfinished: "unfinished";
@@ -798,6 +856,7 @@ export declare const attemptStateSchema: z.ZodObject<{
798
856
  environment: "environment";
799
857
  timeout: "timeout";
800
858
  "provider-auth": "provider-auth";
859
+ stalled: "stalled";
801
860
  "stale-base": "stale-base";
802
861
  "empty-result": "empty-result";
803
862
  unfinished: "unfinished";
@@ -828,6 +887,29 @@ export declare const attemptStateSchema: z.ZodObject<{
828
887
  approvedAt: z.ZodOptional<z.ZodISODateTime>;
829
888
  readyAt: z.ZodOptional<z.ZodISODateTime>;
830
889
  }, z.core.$strict>>;
890
+ liveness: z.ZodOptional<z.ZodObject<{
891
+ state: z.ZodEnum<{
892
+ active: "active";
893
+ stalled: "stalled";
894
+ quiet: "quiet";
895
+ }>;
896
+ at: z.ZodISODateTime;
897
+ lastMovementAt: z.ZodISODateTime;
898
+ activity: z.ZodOptional<z.ZodObject<{
899
+ kind: z.ZodEnum<{
900
+ gate: "gate";
901
+ command: "command";
902
+ agent: "agent";
903
+ step: "step";
904
+ }>;
905
+ label: z.ZodString;
906
+ }, z.core.$strict>>;
907
+ action: z.ZodOptional<z.ZodEnum<{
908
+ report: "report";
909
+ stop: "stop";
910
+ }>>;
911
+ artifact: z.ZodOptional<z.ZodString>;
912
+ }, z.core.$strict>>;
831
913
  timings: z.ZodOptional<z.ZodArray<z.ZodObject<{
832
914
  id: z.ZodString;
833
915
  stage: z.ZodString;
@@ -1264,6 +1346,7 @@ export declare const workStateSchema: z.ZodObject<{
1264
1346
  environment: "environment";
1265
1347
  timeout: "timeout";
1266
1348
  "provider-auth": "provider-auth";
1349
+ stalled: "stalled";
1267
1350
  "stale-base": "stale-base";
1268
1351
  "empty-result": "empty-result";
1269
1352
  unfinished: "unfinished";
@@ -1540,6 +1623,7 @@ export declare const controlStateSchema: z.ZodObject<{
1540
1623
  environment: "environment";
1541
1624
  timeout: "timeout";
1542
1625
  "provider-auth": "provider-auth";
1626
+ stalled: "stalled";
1543
1627
  "stale-base": "stale-base";
1544
1628
  "empty-result": "empty-result";
1545
1629
  unfinished: "unfinished";
@@ -2883,6 +2967,7 @@ export declare const executionDocumentSchema: z.ZodObject<{
2883
2967
  environment: "environment";
2884
2968
  timeout: "timeout";
2885
2969
  "provider-auth": "provider-auth";
2970
+ stalled: "stalled";
2886
2971
  "stale-base": "stale-base";
2887
2972
  "empty-result": "empty-result";
2888
2973
  unfinished: "unfinished";
@@ -3099,6 +3184,7 @@ export declare const executionDocumentSchema: z.ZodObject<{
3099
3184
  environment: "environment";
3100
3185
  timeout: "timeout";
3101
3186
  "provider-auth": "provider-auth";
3187
+ stalled: "stalled";
3102
3188
  "stale-base": "stale-base";
3103
3189
  "empty-result": "empty-result";
3104
3190
  unfinished: "unfinished";
@@ -3211,6 +3297,7 @@ export declare const executionDocumentSchema: z.ZodObject<{
3211
3297
  environment: "environment";
3212
3298
  timeout: "timeout";
3213
3299
  "provider-auth": "provider-auth";
3300
+ stalled: "stalled";
3214
3301
  "stale-base": "stale-base";
3215
3302
  "empty-result": "empty-result";
3216
3303
  unfinished: "unfinished";
@@ -3241,6 +3328,29 @@ export declare const executionDocumentSchema: z.ZodObject<{
3241
3328
  approvedAt: z.ZodOptional<z.ZodISODateTime>;
3242
3329
  readyAt: z.ZodOptional<z.ZodISODateTime>;
3243
3330
  }, z.core.$strict>>;
3331
+ liveness: z.ZodOptional<z.ZodObject<{
3332
+ state: z.ZodEnum<{
3333
+ active: "active";
3334
+ stalled: "stalled";
3335
+ quiet: "quiet";
3336
+ }>;
3337
+ at: z.ZodISODateTime;
3338
+ lastMovementAt: z.ZodISODateTime;
3339
+ activity: z.ZodOptional<z.ZodObject<{
3340
+ kind: z.ZodEnum<{
3341
+ gate: "gate";
3342
+ command: "command";
3343
+ agent: "agent";
3344
+ step: "step";
3345
+ }>;
3346
+ label: z.ZodString;
3347
+ }, z.core.$strict>>;
3348
+ action: z.ZodOptional<z.ZodEnum<{
3349
+ report: "report";
3350
+ stop: "stop";
3351
+ }>>;
3352
+ artifact: z.ZodOptional<z.ZodString>;
3353
+ }, z.core.$strict>>;
3244
3354
  timings: z.ZodOptional<z.ZodArray<z.ZodObject<{
3245
3355
  id: z.ZodString;
3246
3356
  stage: z.ZodString;
@@ -3755,6 +3865,7 @@ export declare const executionDocumentSchema: z.ZodObject<{
3755
3865
  environment: "environment";
3756
3866
  timeout: "timeout";
3757
3867
  "provider-auth": "provider-auth";
3868
+ stalled: "stalled";
3758
3869
  "stale-base": "stale-base";
3759
3870
  "empty-result": "empty-result";
3760
3871
  unfinished: "unfinished";
@@ -34,6 +34,12 @@ export const failureKinds = [
34
34
  'provider-auth',
35
35
  'environment',
36
36
  'timeout',
37
+ /**
38
+ * Процесс попытки жив, но дольше порога политики (`stallSweep.stalledMs`)
39
+ * не выводил, не расходовал процессор и не закрывал стадий: обход
40
+ * controller остановил его. Действие — повтор или правка среды, не кода.
41
+ */
42
+ 'stalled',
37
43
  'stale-base',
38
44
  'empty-result',
39
45
  /** Исполнитель сообщил `completed: false`: работа не доделана, черновик сохранён. */
@@ -54,6 +60,36 @@ export const failureKinds = [
54
60
  'unknown',
55
61
  ];
56
62
  export const failureKindSchema = z.enum(failureKinds);
63
+ /**
64
+ * Живость исполняющейся попытки по периодическому обходу controller
65
+ * (`stallSweep` политики): `active` — движение было недавно, `quiet` — нет
66
+ * движения дольше `quietMs`, `stalled` — дольше `stalledMs`. Движение —
67
+ * вывод процесса, начало или конец его команды, граница стадии
68
+ * (`attempt.stage`), заметный расход процессора деревом процессов.
69
+ */
70
+ export const livenessStates = ['active', 'quiet', 'stalled'];
71
+ export const livenessStateSchema = z.enum(livenessStates);
72
+ /** Что исполняется: вызов агента, gate, шаг среды или прочая команда попытки. */
73
+ export const activitySchema = z.strictObject({
74
+ kind: z.enum(['agent', 'gate', 'step', 'command']),
75
+ label: z.string().min(1).max(300),
76
+ });
77
+ /** Действие controller на `stalled`: остановить процесс или только сообщить. */
78
+ export const stallActionSchema = z.enum(['stop', 'report']);
79
+ /** Последнее состояние живости попытки; пишется только на переходах. */
80
+ export const attemptLivenessSchema = z.strictObject({
81
+ state: livenessStateSchema,
82
+ /** Время обхода, на котором состояние стало текущим. */
83
+ at: isoTimeSchema,
84
+ /** Последнее замеченное движение. */
85
+ lastMovementAt: isoTimeSchema,
86
+ /** Последняя начатая из исполняющихся команд; нет — команды не идут. */
87
+ activity: activitySchema.optional(),
88
+ /** Только у `stalled`: что controller сделал по политике. */
89
+ action: stallActionSchema.optional(),
90
+ /** Только у `stalled`: файл снимка процессов и хвоста вывода. */
91
+ artifact: z.string().max(1000).optional(),
92
+ });
57
93
  /** Значение из отчёта проверки или ответа reviewer: произвольный JSON, сохраняется как есть. */
58
94
  const jsonValue = z.lazy(() => z.union([
59
95
  z.string(),
@@ -451,6 +487,8 @@ export const attemptStateSchema = z.strictObject({
451
487
  wait: z
452
488
  .strictObject({ approvedAt: isoTimeSchema.optional(), readyAt: isoTimeSchema.optional() })
453
489
  .optional(),
490
+ /** Живость исполняющейся попытки (обход controller); нет — обход её не оценивал. */
491
+ liveness: attemptLivenessSchema.optional(),
454
492
  timings: z
455
493
  .array(z.strictObject({
456
494
  id: z.string().min(1),