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.
- package/README.md +23 -15
- package/docs/contracts.md +138 -2
- package/docs/release-notes/0.1.0-alpha.31.md +44 -0
- package/docs/upgrade.md +44 -0
- package/lib/agents/cli-adapter.js +1 -0
- package/lib/cli.js +23 -1
- package/lib/contracts/cli.d.ts +1077 -4
- package/lib/contracts/cli.js +43 -1
- package/lib/contracts/diagnosis.d.ts +2 -1
- package/lib/contracts/diagnosis.js +1 -0
- package/lib/contracts/events.d.ts +414 -5
- package/lib/contracts/events.js +46 -1
- package/lib/contracts/execution.d.ts +112 -1
- package/lib/contracts/execution.js +38 -0
- package/lib/contracts/handoff.d.ts +694 -0
- package/lib/contracts/handoff.js +291 -0
- package/lib/contracts/index.d.ts +1 -0
- package/lib/contracts/index.js +1 -0
- package/lib/contracts/policy.d.ts +27 -1
- package/lib/contracts/policy.js +38 -2
- package/lib/contracts/published.d.ts +841 -2
- package/lib/contracts/published.js +2 -0
- package/lib/contracts/repair-policy.js +5 -0
- package/lib/contracts/report.d.ts +2 -0
- package/lib/control/harness.d.ts +37 -11
- package/lib/control/harness.js +3 -0
- package/lib/control/recovery.d.ts +1 -1
- package/lib/engine/engine.d.ts +15 -7
- package/lib/engine/engine.js +24 -0
- package/lib/engine/joint-runner.d.ts +6 -0
- package/lib/engine/joint-runner.js +20 -4
- package/lib/engine/property-recovery.js +1 -0
- package/lib/engine/reuse.js +1 -0
- package/lib/engine/runner.d.ts +8 -0
- package/lib/engine/runner.js +116 -11
- package/lib/engine/stall-sweep.d.ts +137 -0
- package/lib/engine/stall-sweep.js +393 -0
- package/lib/environment/activity.d.ts +34 -0
- package/lib/environment/activity.js +55 -0
- package/lib/environment/lifecycle.js +1 -0
- package/lib/environment/process.d.ts +7 -1
- package/lib/environment/process.js +14 -0
- package/lib/environment/redaction.d.ts +2 -0
- package/lib/environment/redaction.js +19 -0
- package/lib/explain/state.d.ts +1 -1
- package/lib/explain/state.js +12 -0
- package/lib/handoff/index.d.ts +2 -0
- package/lib/handoff/index.js +3 -0
- package/lib/handoff/markdown.d.ts +6 -0
- package/lib/handoff/markdown.js +153 -0
- package/lib/handoff/pack.d.ts +49 -0
- package/lib/handoff/pack.js +492 -0
- package/lib/index.d.ts +2 -1
- package/lib/index.js +1 -0
- package/lib/integrations/connector/redact.d.ts +2 -13
- package/lib/integrations/connector/redact.js +2 -21
- package/lib/projections/attempt.d.ts +28 -0
- package/lib/projections/attempt.js +14 -0
- package/lib/projections/stop.d.ts +11 -1
- package/lib/projections/stop.js +29 -0
- package/lib/report/compute.js +1 -0
- package/lib/storage/document.d.ts +28 -6
- package/lib/storage/sqlite.d.ts +2 -0
- package/lib/storage/sqlite.js +9 -1
- package/lib/verification/gates-at.d.ts +11 -1
- package/lib/verification/gates-at.js +28 -2
- package/lib/verification/gates.d.ts +3 -1
- package/lib/verification/gates.js +5 -0
- package/package.json +1 -1
- package/schemas/execution-document.schema.json +68 -0
- package/schemas/execution-policy.schema.json +32 -0
- package/schemas/handoff-pack.schema.json +1424 -0
- package/schemas/run-event.schema.json +360 -0
- package/schemas/stop-diagnosis.schema.json +1 -0
- package/schemas/value-report.schema.json +1 -0
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
|
|
|
5
5
|
интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
|
|
6
6
|
и доказательствами.
|
|
7
7
|
|
|
8
|
-
> Статус: `0.1.0-alpha.
|
|
8
|
+
> Статус: `0.1.0-alpha.31` — предварительный выпуск (alpha). Договоры
|
|
9
9
|
> `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
|
|
10
10
|
> Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
|
|
11
11
|
> ограниченным восстановлением, повторным использованием кандидата, бюджетами,
|
|
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
|
|
|
28
28
|
Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
|
|
29
29
|
|
|
30
30
|
```sh
|
|
31
|
-
npm install --save-exact devcontour-harness@0.1.0-alpha.
|
|
31
|
+
npm install --save-exact devcontour-harness@0.1.0-alpha.31 # точная версия
|
|
32
32
|
# или: npm install --save-exact devcontour-harness@alpha # текущая alpha
|
|
33
33
|
npx harness --version
|
|
34
34
|
```
|
|
@@ -90,19 +90,20 @@ git rev-parse refs/heads/harness/accepted # совпадает с data.result.
|
|
|
90
90
|
|
|
91
91
|
## Команды
|
|
92
92
|
|
|
93
|
-
| Команда
|
|
94
|
-
|
|
|
95
|
-
| `validate --graph F --policy F`
|
|
96
|
-
| `review-plan / review-contract … --author A`
|
|
97
|
-
| `approve --state D --subject ID --digest H`
|
|
98
|
-
| `run --graph F --policy F --state D`
|
|
99
|
-
| `status / events / result --state D`
|
|
100
|
-
| `pause / resume / cancel / retry --state D`
|
|
101
|
-
| `deliver --state D --work ID --sink file:D`
|
|
102
|
-
| `worktree-cleanup --state D [--dry-run]`
|
|
103
|
-
| `profile --profile ID [--repository D]`
|
|
104
|
-
| `doctor`
|
|
105
|
-
| `report --state D [--format md\|html]`
|
|
93
|
+
| Команда | Что делает |
|
|
94
|
+
| ----------------------------------------------- | -------------------------------------------------- |
|
|
95
|
+
| `validate --graph F --policy F` | Проверка входов без моделей и записи |
|
|
96
|
+
| `review-plan / review-contract … --author A` | Раунд технического ревью с историей находок |
|
|
97
|
+
| `approve --state D --subject ID --digest H` | Согласование оператором (`approvalMode: operator`) |
|
|
98
|
+
| `run --graph F --policy F --state D` | Регистрация, согласование и работа до простоя |
|
|
99
|
+
| `status / events / result --state D` | Чтение без побочных эффектов |
|
|
100
|
+
| `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
|
|
101
|
+
| `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
|
|
102
|
+
| `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
|
|
103
|
+
| `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
|
|
104
|
+
| `doctor` | Версии, runtime, sandbox, совместимость состояния |
|
|
105
|
+
| `report --state D [--format md\|html]` | Отчёт об эффекте по данным проекта |
|
|
106
|
+
| `handoff --state D [--format md] [--intent T]…` | Пакет передачи контекста новой сессии агента |
|
|
106
107
|
|
|
107
108
|
stdout — один JSON (`devcontour-harness/v1alpha1`), диагностика — stderr. Exit
|
|
108
109
|
codes: 0 успех, 2 неверный вход, 3 отказ/блокировка, 4 инфраструктура.
|
|
@@ -146,6 +147,13 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
|
|
|
146
147
|
`devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
|
|
147
148
|
Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
|
|
148
149
|
|
|
150
|
+
## Выпуск 0.1.0-alpha.31
|
|
151
|
+
|
|
152
|
+
Controller сам замечает зависшие попытки и проверки (`stallSweep`, отказ
|
|
153
|
+
`stalled`), а `harness handoff` собирает пакет передачи контекста новой сессии
|
|
154
|
+
агента из хранилища.
|
|
155
|
+
Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.31.md).
|
|
156
|
+
|
|
149
157
|
## Выпуск 0.1.0-alpha.30
|
|
150
158
|
|
|
151
159
|
Отчёт об эффекте `harness report`, события стадий и `status --detail` для
|
package/docs/contracts.md
CHANGED
|
@@ -33,7 +33,8 @@ refs, варианты исходов. Связи **между** значени
|
|
|
33
33
|
Опубликованы: `work-order`, `work-graph`, `execution-policy`,
|
|
34
34
|
`context-snapshot`, `contract-document`, `run-result`, `result-envelope`,
|
|
35
35
|
`run-event`, `review-record`, `joint-verification`, `execution-document`,
|
|
36
|
-
`value-report` (отчёт `harness report`, см. «ValueReport»)
|
|
36
|
+
`value-report` (отчёт `harness report`, см. «ValueReport»), `handoff-pack`
|
|
37
|
+
(пакет `harness handoff`, см. «HandoffPack»).
|
|
37
38
|
|
|
38
39
|
## Версии
|
|
39
40
|
|
|
@@ -108,6 +109,7 @@ manifest снимка и в необязательном поле `baseline` о
|
|
|
108
109
|
| `toolProfiles{}`, `environment`, `lifecycle`, `resources[]` | Инструменты (у профиля — встроенные инструменты claude, shell и сеть codex, MCP-серверы `mcp{}`: stdio-команда или http-адрес, только перечисленные `tools`, учётные данные — именами переменных `env`/`bearerTokenEnv`, передаются CLI по имени), среда, ресурсы (порты 1024–65535) |
|
|
109
110
|
| `concurrency`, `leaseMs`, `runTimeoutMs`, `reviewProbes` | Пределы исполнения |
|
|
110
111
|
| `maxAttempts`, `repairBudget`, `reuseImplementation` | Повторы и повторное использование кандидата |
|
|
112
|
+
| `stallSweep{intervalMs, quietMs, stalledMs, action}` | Необязательное: обход зависших попыток controller ([ниже](#зависшие-попытки)); нет поля — 30 000 / 180 000 / 600 000 мс и `report`, умолчание не подставляется и digest политики не меняет |
|
|
111
113
|
| `reviewProtocolRetries` | Необязательное: дополнительные вызовы reviewer кода при ошибке протокола ответа (0–2; нет поля — 1, умолчание не подставляется и digest политики не меняет), [review-protocol.md](review-protocol.md) |
|
|
112
114
|
| `budgets{work, group, total, onUnknown}`, `prices[]` | Пределы USD и/или времени; тарифы |
|
|
113
115
|
|
|
@@ -613,6 +615,51 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
|
|
|
613
615
|
закреплён, `impact` может нести только ссылку на базовую проверку
|
|
614
616
|
(`baseline`), выбранную хостом для режима `affected`.
|
|
615
617
|
|
|
618
|
+
### Зависшие попытки
|
|
619
|
+
|
|
620
|
+
Controller, ведущий очередь, раз в `stallSweep.intervalMs` (не меньше 1000 мс
|
|
621
|
+
и не больше `quietMs`) обходит исполняющиеся попытки. Движение попытки —
|
|
622
|
+
начало и конец её команды (вызов агента, gate, шаг среды, прочие команды),
|
|
623
|
+
вывод в stdout/stderr, граница стадии (`attempt.stage`) и прирост
|
|
624
|
+
процессорного времени дерева процессов исполняющихся команд (сумма
|
|
625
|
+
положительных приростов по каждому процессу, новый — от нуля) не меньше 1 %
|
|
626
|
+
прошедшего времени. Смена состава дерева сама движением не считается: цикл
|
|
627
|
+
ожидания (`until nc -z db 5432; do sleep 1; done`) рождает процессы, не
|
|
628
|
+
продвигаясь. Один `ps` на обход, общий для одновременных обходов; перерыв
|
|
629
|
+
от конца прошлого обхода дольше трёх интервалов (сон машины, занятый event
|
|
630
|
+
loop) начинает отсчёт заново, но не больше двух раз подряд.
|
|
631
|
+
|
|
632
|
+
Состояния: `active`; `quiet` — нет движения дольше `quietMs`; `stalled` —
|
|
633
|
+
дольше `stalledMs` (`quietMs < stalledMs`). Без данных `ps` о процессах
|
|
634
|
+
(отказ, Windows, нет времени процесса) оценка идёт только по выводу и не
|
|
635
|
+
поднимается выше `quiet` (`cpuUnavailable` в событии). Попытка без
|
|
636
|
+
исполняющейся команды (ждёт hook, ресурс, интеграцию) оценивается от последнего
|
|
637
|
+
движения с порогом `stalledMs` и тоже не выше `quiet`. Переход пишется в
|
|
638
|
+
`AttemptState.liveness` и событием `attempt.liveness` одной транзакцией под
|
|
639
|
+
fencing; само состояние между переходами не перезаписывается, а незаписанный
|
|
640
|
+
временным отказом переход повторяет следующий обход (не больше пяти раз;
|
|
641
|
+
отказ движка или схемы не повторяется). На `stalled` — снимок процессов
|
|
642
|
+
исполняющихся команд (pid, родитель, процессорное время, команда под маской
|
|
643
|
+
среды; команда без маски не сохраняется) и хвост вывода: в
|
|
644
|
+
`artifacts/<runId>/stall-<эпизод>.json` (один на эпизод, записывается первым) и в событии (≤ 20
|
|
645
|
+
процессов, ≤ 2000 символов). Дальше — `action`: `report` только сообщает
|
|
646
|
+
(попытка идёт до своего предела времени, движение вернёт `active`), `stop`
|
|
647
|
+
останавливает попытку отказом класса `stalled`: повтор или правка среды, а не
|
|
648
|
+
правка кода (`repairPolicy.stalled`, бюджет попыток он тратит, как `timeout`);
|
|
649
|
+
при `stop` зависшая попытка останавливается, даже если переход не записан.
|
|
650
|
+
Совместная проверка и gates на SHA вне попытки (`runGatesAt`) ведут свой
|
|
651
|
+
обход: переходы проверки — событие `joint.liveness` под её fencing, переходы
|
|
652
|
+
`runGatesAt` — `onLiveness` хоста и `liveness[]` результата (нагрузка как у
|
|
653
|
+
`attempt.liveness`, без файла снимка); при `stop` они останавливаются с
|
|
654
|
+
текстом зависания. `stallSweep` — надзор, а не условие
|
|
655
|
+
исполнения: в digest исполнения (основания попыток и reuse) он не входит.
|
|
656
|
+
|
|
657
|
+
`status` показывает `works[].liveness` (`quiet`/`stalled`) у активной попытки
|
|
658
|
+
без движения, `status --detail` — `detail.attempts[].liveness` (`state`,
|
|
659
|
+
`since`, `lastMovementAt`, `idleMs`, `activity`, `action`), `explain` —
|
|
660
|
+
причину `stalled` у работающего поручения: при `report` действует человек
|
|
661
|
+
(`fix-environment`), при `stop` — controller.
|
|
662
|
+
|
|
616
663
|
### RunEvent
|
|
617
664
|
|
|
618
665
|
`{apiVersion, seq, at, type, graphId?, workId?, runId?, attempt?, payload}`.
|
|
@@ -634,6 +681,12 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
|
|
|
634
681
|
под fencing: утративший владение не пишет ни замера, ни события. Повторное
|
|
635
682
|
закрытие замера ничего не меняет и событий не создаёт.
|
|
636
683
|
|
|
684
|
+
`attempt.liveness` — переход живости попытки по обходу controller:
|
|
685
|
+
`{state, previous, lastMovementAt, idleMs, activity?: {kind:
|
|
686
|
+
'agent'|'gate'|'step'|'command', label}, cpuUnavailable?, action?:
|
|
687
|
+
'stop'|'report', snapshot?}`; `joint.liveness` — то же с `verificationId`; `action` и `snapshot` — только у `stalled` (см. «Зависшие
|
|
688
|
+
попытки»).
|
|
689
|
+
|
|
637
690
|
`finished` может не прийти: поздний finish владельца, утратившего срок,
|
|
638
691
|
отклоняется (runner его не повторяет), упавший процесс его не пишет, а `adopt`
|
|
639
692
|
и recovery открытые замеры прежнего владельца не закрывают. Такая стадия
|
|
@@ -789,6 +842,78 @@ prompt, вывода runtime, текстов находок, ошибок и п
|
|
|
789
842
|
недели без активности — `gap`), 50 строк gates и стадий; JSON ≤ 512 КБ,
|
|
790
843
|
HTML ≤ 1 МБ. Усечение отмечено флагом и ограничением.
|
|
791
844
|
|
|
845
|
+
### HandoffPack
|
|
846
|
+
|
|
847
|
+
Пакет передачи контекста (`harness handoff`, `handoffPack(harness, options)`
|
|
848
|
+
и `handoffMarkdown(pack)` из корня пакета; `handoffVersion: 1`,
|
|
849
|
+
`handoffPackSchema`, `schemas/handoff-pack.schema.json`). Ведущий агент хоста,
|
|
850
|
+
который ведёт доску через много попыток, начинает новую сессию с пакета, а не
|
|
851
|
+
с пересказа предыдущей: факты собираются из хранилища теми же проекциями, что
|
|
852
|
+
`status --detail` и `explain`, и только читают состояние.
|
|
853
|
+
|
|
854
|
+
- `summary`, `limits` — счёт поручений по статусам, `maxAttempts` и
|
|
855
|
+
`repairBudget` политики;
|
|
856
|
+
- `queue`, `controller` — пауза выдачи, её причина и кто её снимает
|
|
857
|
+
(`queueStop`, `queuePause`), операция, держащая паузу (`operation`), и
|
|
858
|
+
классы отказа паузы runtime (`failures`); держатель роли controller и
|
|
859
|
+
свежесть срока;
|
|
860
|
+
- `active` — идущие попытки: стадия и её длительность, heartbeat, gates
|
|
861
|
+
текущей фазы (`attemptView`); `unfinished` — незакрытые записи попыток с
|
|
862
|
+
истёкшим владением или такие, которые поручение уже не ведёт;
|
|
863
|
+
- `works` — открытые поручения (идущие, упавшие, план, остальные): класс и
|
|
864
|
+
причина провала, удержание, эпизод восстановления с предложением,
|
|
865
|
+
блокировки (без общей паузы очереди; сверх предела — `blockersTruncated`) и
|
|
866
|
+
`next` — кто и что делает (по диагнозу `explain`; стадия и свойство — по
|
|
867
|
+
`nextAction`);
|
|
868
|
+
- `stops` — диагнозы `explain` без проб runtime, кроме `action: none`.
|
|
869
|
+
Остановка выдачи общей паузой очереди — одна запись с `queue: true` без
|
|
870
|
+
`workId`; одинаковые остановки на выдаче у разных поручений тоже
|
|
871
|
+
свёрнуты; `works` — первые 20 затронутых, `worksCount` — сколько всего.
|
|
872
|
+
Решения (`actor` lead или user и действие не `wait`) идут первыми;
|
|
873
|
+
- `failures` — последние провалившиеся и истёкшие попытки, новые первыми:
|
|
874
|
+
`failureKind`, код (`stopCodeOf`), текст ошибки и текущий статус
|
|
875
|
+
поручения (`workStatus`);
|
|
876
|
+
- `budgets` — общий бюджет и бюджеты групп (с `--graph` — только его
|
|
877
|
+
группа), бюджеты поручений — только с расходом или не в пределах:
|
|
878
|
+
сообщено (`reportedUsd`) и оценено (`estimatedUsd`) против предела, время,
|
|
879
|
+
`complete` и причины неполноты (вызовы без стоимости, незавершённые,
|
|
880
|
+
брошенные, попытки без учёта); при неполном расходе сумма — нижняя граница
|
|
881
|
+
(«≥ $X (неполно: …)» в Markdown), остаток — `null`. `repairs` —
|
|
882
|
+
восстановления незавершённых заданий графов;
|
|
883
|
+
- `next` — следующий шаг доски: первое решение; иначе идущая попытка со
|
|
884
|
+
свежим сроком владения — ждать (без controller — до `leaseUntil`); попытка
|
|
885
|
+
с истёкшим сроком или очередь без controller — `command: "harness run"` (run истечёт брошенную
|
|
886
|
+
попытку и продолжит очередь); пауза оператора — `"harness resume"`; иначе
|
|
887
|
+
первый открытый шаг поручения;
|
|
888
|
+
- `intentions` — единственный текст не из хранилища: намерения агента.
|
|
889
|
+
|
|
890
|
+
Пределы (`HANDOFF_LIMITS`): 50 открытых поручений, 30 остановок (после
|
|
891
|
+
свёртки) с 5 ссылками evidence каждая, 10 провалов, 20 незавершённых
|
|
892
|
+
попыток, 3 блокировки на поручение, 20 строк бюджетов, 10 заданий, 20
|
|
893
|
+
намерений по 1000 знаков. Тексты из хранилища и намерения очищаются от
|
|
894
|
+
escape-последовательностей терминала (ANSI CSI, OSC), серия управляющих
|
|
895
|
+
символов заменяется пробелом; строки фактов усечены до 300 знаков, имена и
|
|
896
|
+
идентификаторы — до 200, с «…» и без разрыва суррогатной пары. Пакет не
|
|
897
|
+
больше `HANDOFF_MAX_BYTES` (256 КБ UTF-8): сверх него записи отбрасываются в
|
|
898
|
+
порядке «намерения с конца, старые провалы, поручения без решения,
|
|
899
|
+
остановки без решения, незавершённые попытки, остальные поручения и
|
|
900
|
+
остановки, строки бюджетов» (`truncated.bySize`), отказа по размеру нет.
|
|
901
|
+
Сколько записей каждого списка не вошло — `truncated`; бюджеты поручений в
|
|
902
|
+
пределах и без расхода не показываются намеренно и считаются отдельно
|
|
903
|
+
(`budgetsWithin`), усечённые и отброшенные намерения — `intentions` и
|
|
904
|
+
`intentionsDropped`. Тексты из хранилища маскируются по значениям секретов
|
|
905
|
+
политики из окружения читающего процесса (`policySecrets`, как у
|
|
906
|
+
коннектора): секрет, которого в этом окружении нет, маска не знает —
|
|
907
|
+
библиотеке можно передать свою `redact`. Fencing-токены в пакет не
|
|
908
|
+
попадают.
|
|
909
|
+
|
|
910
|
+
Весь пакет — один снимок хранилища: `handoffPack` выполняет status,
|
|
911
|
+
диагнозы и чтение заданий графов внутри одного `read`
|
|
912
|
+
(`SqliteExecutionStore.read` вложенным чтением использует снимок внешнего,
|
|
913
|
+
без второго `BEGIN`). Попытка со свежим сроком владения без живого
|
|
914
|
+
controller — `next` «ждать до `leaseUntil` или проверить процесс-владелец»
|
|
915
|
+
без команды; `harness run` называется только для попытки с истёкшим сроком.
|
|
916
|
+
|
|
792
917
|
## Порты
|
|
793
918
|
|
|
794
919
|
| Порт | Договор |
|
|
@@ -942,6 +1067,7 @@ stdout — один JSON `CliEnvelope`: `{apiVersion, command, ok: true, data}`
|
|
|
942
1067
|
| `init` | `--repository D [--profile P] [--writer R] [--state D] [--plan]` | да | план файлов, `created`, `manifest`, `facts`, `toolchain`, `next` | Create-only `.harness/`, manifest до политики, политика последней; повтор — `created: []`; иное решение — `PATH_CONFLICT` |
|
|
943
1068
|
| `explain` | `--state D --policy F [--work ID]` | нет | `diagnoses[]` (`StopDiagnosis`) | Только чтение: без повторов, вызовов моделей и изменений состояния |
|
|
944
1069
|
| `report` | `--state D [--since T\|Nd\|Nw] [--until T] [--as-of T] [--format json\|md\|html] [--no-titles] [--out F]` | нет | `ValueReport`; с `--out` — `{out, format, bytes, asOf}` | Только чтение; те же данные и параметры — те же байты |
|
|
1070
|
+
| `handoff` | `--state D [--graph ID] [--intent T]… [--format json\|md]` | нет | `HandoffPack`; с `--format md` — Markdown без конверта | Только чтение; агент добавляет только намерения |
|
|
945
1071
|
| `plan-request` | `--brief F --policy F [--context F] [--contracts D] [--requirements [R:]F]… [--human]` | нет | `prompt`, `readOnly`, `recommendedTasks`, `maxTasks`, `basis`, `facts` (`PlanningFacts`) | Чистая функция входов: та же постановка и те же факты — тот же prompt и `basis`; модель не вызывается |
|
|
946
1072
|
| `plan-check` | `--draft F --policy F [--context F] [--contracts D] [--brief F [--basis H]]` | нет | `issues`, `checkPlan`; без проблем — `graph`, `graphDigest`, `basis` | Чистая функция входов и `HEAD` источников требований; согласования не выдаёт, gates не запускает; расхождение `--basis` — `APPROVAL_STALE` |
|
|
947
1073
|
| `capabilities` | — | нет | каталог общих операций (`OperationCatalog`) | Чистая функция установленной версии пакета |
|
|
@@ -974,10 +1100,20 @@ md|html` — документированное исключение, как `--
|
|
|
974
1100
|
`INVALID_INPUT`; stdout — конверт `{out, format, bytes, asOf}`. Неверное
|
|
975
1101
|
окно (`--since` не раньше `--until`, время без пояса) — `INVALID_INPUT`;
|
|
976
1102
|
нет каталога — `NOT_FOUND`, каталог не создаётся. Флаги `--since`,
|
|
977
|
-
`--until`, `--as-of`, `--
|
|
1103
|
+
`--until`, `--as-of`, `--no-titles` принимает только `report` (`--format` — ещё
|
|
1104
|
+
`handoff`, со значениями json и md).
|
|
978
1105
|
Пределы размера (JSON 512 КБ, HTML и Markdown 1 МБ) проверяют сами
|
|
979
1106
|
`valueReport` и рендеры (`assertReportBytes`, `INTERNAL`).
|
|
980
1107
|
|
|
1108
|
+
**`handoff`.** Открывает каталог состояния только для чтения (политика — из
|
|
1109
|
+
`binding.json`, как у `status`) и строит `HandoffPack`. `--format json` (по
|
|
1110
|
+
умолчанию) — обычный конверт; `--format md` — документированное исключение,
|
|
1111
|
+
как у `report`: успешный ответ печатается Markdown без конверта. Отказ —
|
|
1112
|
+
JSON-конверт в обоих режимах; нет каталога — `NOT_FOUND`, каталог не
|
|
1113
|
+
создаётся; неизвестный `--graph` — `NOT_FOUND`; больше 20 `--intent` или
|
|
1114
|
+
`--format` не json/md — `INVALID_INPUT`. `--intent` принимает только
|
|
1115
|
+
`handoff`, `--format` — `report` и `handoff`.
|
|
1116
|
+
|
|
981
1117
|
**Причина отказа окружения `dependency-network`.** Установка зависимостей,
|
|
982
1118
|
упавшая на сети или реестре пакетов, получает класс `environment`, а не `gate`
|
|
983
1119
|
(правило — [архитектура](architecture.md#что-гарантируется), «Сеть и реестр при установке зависимостей»). Отдельного поля
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# devcontour-harness 0.1.0-alpha.31
|
|
2
|
+
|
|
3
|
+
Controller сам замечает зависшие попытки и проверки, не дожидаясь вопроса
|
|
4
|
+
человека, а новая сессия ведущего агента начинает с пакета передачи из
|
|
5
|
+
хранилища, а не с пересказа прошлой. Обязательные gates, fencing и привязка
|
|
6
|
+
доказательств к SHA не меняются; `stateVersion` и `policyVersion` прежние.
|
|
7
|
+
|
|
8
|
+
## Изменения
|
|
9
|
+
|
|
10
|
+
- **Обход зависаний.** Controller, ведущий очередь, раз в
|
|
11
|
+
`stallSweep.intervalMs` оценивает исполняющиеся попытки: вывод, начало и
|
|
12
|
+
конец команд, границы стадий и прирост процессорного времени дерева
|
|
13
|
+
процессов. Состояния `active` → `quiet` → `stalled` пишутся в
|
|
14
|
+
`AttemptState.liveness` и событием `attempt.liveness` под fencing; у
|
|
15
|
+
совместной проверки — `joint.liveness`, у `runGatesAt` — `onLiveness` и
|
|
16
|
+
`liveness[]` результата. Цикл ожидания, рождающий процессы без прогресса,
|
|
17
|
+
движением не считается. На `stalled` — снимок процессов (команды под маской
|
|
18
|
+
среды) и хвост вывода в `artifacts/<runId>/stall-<эпизод>.json`.
|
|
19
|
+
- **Политика `stallSweep`.** `{intervalMs, quietMs, stalledMs, action}`;
|
|
20
|
+
без поля — 30 с / 3 мин / 10 мин и `report` (только сообщить). `stop`
|
|
21
|
+
останавливает попытку отказом нового класса `stalled`: повтор или правка
|
|
22
|
+
среды, а не правка кода (`repairPolicy.stalled`). Поле — надзор, в digest
|
|
23
|
+
исполнения не входит: основания попыток и reuse не меняются.
|
|
24
|
+
- **Живость в `status`, `status --detail` и `explain`.** `works[].liveness`
|
|
25
|
+
у активной попытки без движения, `detail.attempts[].liveness`, причина
|
|
26
|
+
`stalled` у работающего поручения с действием человека или controller.
|
|
27
|
+
- **`harness handoff`.** Пакет передачи контекста из одного снимка
|
|
28
|
+
хранилища: активные и незавершённые попытки, открытые поручения со
|
|
29
|
+
следующим шагом, остановки (решения первыми), последние провалы, бюджеты и
|
|
30
|
+
следующий шаг доски; агент добавляет только намерения (`--intent`). JSON
|
|
31
|
+
по умолчанию, `--format md` — Markdown; `--graph` сужает до одного графа.
|
|
32
|
+
Размер ограничен 256 КБ с отбрасыванием записей по порядку важности,
|
|
33
|
+
тексты очищены от управляющих последовательностей и маскируются по
|
|
34
|
+
секретам политики. Библиотека: `handoffPack`, `handoffMarkdown`,
|
|
35
|
+
`handoffPackSchema`, схема `schemas/handoff-pack.schema.json`.
|
|
36
|
+
- **Вложенное чтение хранилища.** `SqliteExecutionStore.read` внутри другого
|
|
37
|
+
`read` использует снимок внешнего, без второго `BEGIN`.
|
|
38
|
+
|
|
39
|
+
## Обновление
|
|
40
|
+
|
|
41
|
+
Пакет alpha.30 остаётся неизменным. Обход включён по умолчанию (`report`),
|
|
42
|
+
поэтому первая же затихшая попытка запишет `liveness` в документ состояния, а
|
|
43
|
+
alpha.30 и ниже такой документ не прочитают. Откатывайтесь вместе с копией
|
|
44
|
+
состояния, снятой до обновления. Подробнее — `docs/upgrade.md`.
|
package/docs/upgrade.md
CHANGED
|
@@ -313,6 +313,50 @@ install|fetch` или `yarn install`;
|
|
|
313
313
|
возвращается прежняя классификация; уже записанные попытки сохраняют свой
|
|
314
314
|
класс.
|
|
315
315
|
|
|
316
|
+
### alpha.31: обход зависаний
|
|
317
|
+
|
|
318
|
+
Номера форматов прежние (`stateVersion: 1`, `policyVersion: 1`), новое —
|
|
319
|
+
аддитивно:
|
|
320
|
+
|
|
321
|
+
- **Состояние.** Необязательное поле `AttemptState.liveness` (`state`, `at`,
|
|
322
|
+
`lastMovementAt`, `activity`, `action`, `artifact`) и класс отказа
|
|
323
|
+
`stalled` в `failureKind`. Поле пишется только на переходах живости.
|
|
324
|
+
- **Политика.** Необязательное поле
|
|
325
|
+
`stallSweep{intervalMs, quietMs, stalledMs, action}` и
|
|
326
|
+
`repairPolicy.stalled`. Без поля обход идёт с
|
|
327
|
+
умолчаниями (30 000 / 180 000 / 600 000 мс, `report`); умолчание в
|
|
328
|
+
политику не подставляется, digest политики и digest исполнения прежние,
|
|
329
|
+
поэтому основания попыток и reuse кандидатов после обновления не меняются.
|
|
330
|
+
- **Журнал.** События `attempt.liveness` и `joint.liveness`. Файлы снимков
|
|
331
|
+
`artifacts/<runId>/stall-<эпизод>.json` в каталоге состояния.
|
|
332
|
+
- **Хост.** `runGatesAt` принимает `onLiveness` и возвращает `liveness[]`;
|
|
333
|
+
`status` — `works[].liveness`, `status --detail` —
|
|
334
|
+
`detail.attempts[].liveness`.
|
|
335
|
+
|
|
336
|
+
**Откат.** Документ состояния и политика разбираются строго: alpha.30 и ниже
|
|
337
|
+
отказывают на документе, где у попытки есть `liveness` или отказ `stalled`, и
|
|
338
|
+
на политике с `stallSweep`. Обход включён по умолчанию, поэтому такой документ
|
|
339
|
+
появляется с первой затихшей попыткой. Путь — строка «Новая версия уже
|
|
340
|
+
изменила формат» таблицы [«Откат»](#откат): остановить writers, восстановить
|
|
341
|
+
копию каталога состояния, снятую до обновления, вместе с прежней версией
|
|
342
|
+
пакета и убрать `stallSweep` из политики. События `attempt.liveness` alpha.30
|
|
343
|
+
читает как `unknown`.
|
|
344
|
+
|
|
345
|
+
### alpha.31: пакет передачи контекста
|
|
346
|
+
|
|
347
|
+
Только чтение: формат состояния, политики и событий не меняется. Новое —
|
|
348
|
+
команда
|
|
349
|
+
`harness handoff --state D [--graph ID] [--intent T]… [--format json|md]`,
|
|
350
|
+
функции `handoffPack` и `handoffMarkdown` и схема
|
|
351
|
+
`handoffPackSchema` (`schemas/handoff-pack.schema.json`, `handoffVersion: 1`)
|
|
352
|
+
из корня пакета. `handoffPack` вызывает `read` хранилища вложенно;
|
|
353
|
+
`SqliteExecutionStore` во вложенном чтении использует снимок внешнего, без
|
|
354
|
+
второго `BEGIN`. Хранилище хоста со своим `read` должно допускать вложенный
|
|
355
|
+
вызов.
|
|
356
|
+
|
|
357
|
+
**Откат.** Ниже этой версии команды `handoff` нет; состояние она не меняла,
|
|
358
|
+
поэтому откат пакета копии не требует.
|
|
359
|
+
|
|
316
360
|
## Перед обновлением
|
|
317
361
|
|
|
318
362
|
1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
|
|
@@ -296,6 +296,7 @@ export function cliAdapter(runtime, options = {}) {
|
|
|
296
296
|
const telemetry = usageStream(runtime);
|
|
297
297
|
try {
|
|
298
298
|
result = await command(argv, r.cwd, {
|
|
299
|
+
activity: { kind: 'agent', label: `${runtime} ${r.task}`.slice(0, 300) },
|
|
299
300
|
contain: { dirs: review ? [] : r.sandbox.writable },
|
|
300
301
|
onRawStdout: (text) => {
|
|
301
302
|
telemetry.push(text);
|
package/lib/cli.js
CHANGED
|
@@ -25,6 +25,7 @@ import { SqliteExecutionStore } from "./storage/sqlite.js";
|
|
|
25
25
|
import { collectReportInput } from "./control/report.js";
|
|
26
26
|
import { writeReportFile } from "./control/report-file.js";
|
|
27
27
|
import { valueReport, reportHtml, reportMarkdown } from "./report/index.js";
|
|
28
|
+
import { handoffMarkdown, handoffPack } from "./handoff/index.js";
|
|
28
29
|
const usage = `harness ${HARNESS_VERSION}
|
|
29
30
|
|
|
30
31
|
Использование: harness <команда> [параметры]
|
|
@@ -221,6 +222,7 @@ const options = {
|
|
|
221
222
|
'as-of': { type: 'string' },
|
|
222
223
|
format: { type: 'string' },
|
|
223
224
|
'no-titles': { type: 'boolean' },
|
|
225
|
+
intent: { type: 'string', multiple: true },
|
|
224
226
|
};
|
|
225
227
|
/** Новые флаги H1 допустимы только у своих команд; прежние команды их не принимают. */
|
|
226
228
|
const flagOwners = {
|
|
@@ -237,8 +239,9 @@ const flagOwners = {
|
|
|
237
239
|
since: ['report'],
|
|
238
240
|
until: ['report'],
|
|
239
241
|
'as-of': ['report'],
|
|
240
|
-
format: ['report'],
|
|
242
|
+
format: ['report', 'handoff'],
|
|
241
243
|
'no-titles': ['report'],
|
|
244
|
+
intent: ['handoff'],
|
|
242
245
|
};
|
|
243
246
|
/** Явное человеческое представление успешного ответа (`--human`). */
|
|
244
247
|
const presenters = {
|
|
@@ -629,6 +632,25 @@ async function run(argv) {
|
|
|
629
632
|
data: { out: v.out, format, bytes: Buffer.byteLength(text), asOf: report.window.asOf },
|
|
630
633
|
};
|
|
631
634
|
}
|
|
635
|
+
case 'handoff': {
|
|
636
|
+
const format = v.format ?? 'json';
|
|
637
|
+
if (format !== 'json' && format !== 'md')
|
|
638
|
+
throw new HarnessError('INVALID_INPUT', '--format: для handoff ожидается json или md', [
|
|
639
|
+
{ path: ['--format'], message: format },
|
|
640
|
+
]);
|
|
641
|
+
const h = open(need('state'), binding(need('state')), 'state');
|
|
642
|
+
try {
|
|
643
|
+
const data = handoffPack(h, {
|
|
644
|
+
...optional('graphId', v.graph),
|
|
645
|
+
...optional('intentions', v.intent),
|
|
646
|
+
});
|
|
647
|
+
// JSON-конверт по умолчанию; --format md — текст, как у report. Отказ — JSON.
|
|
648
|
+
return { command, data, ...(format === 'md' ? { text: handoffMarkdown(data) } : {}) };
|
|
649
|
+
}
|
|
650
|
+
finally {
|
|
651
|
+
h.close();
|
|
652
|
+
}
|
|
653
|
+
}
|
|
632
654
|
case 'plan-request': {
|
|
633
655
|
const b = loadPolicy(need('policy'));
|
|
634
656
|
const first = b.policy.repositories[0]?.id ?? 'main';
|