devcontour-harness 0.1.0-alpha.29 → 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 +50 -14
- package/docs/architecture.md +64 -0
- package/docs/compatibility.md +15 -14
- package/docs/contracts.md +380 -26
- package/docs/release-notes/0.1.0-alpha.30.md +40 -0
- package/docs/release-notes/0.1.0-alpha.31.md +44 -0
- package/docs/review-probes.md +17 -17
- package/docs/upgrade.md +137 -0
- package/lib/agents/cli-adapter.js +1 -0
- package/lib/agents/review-probe.d.ts +1 -0
- package/lib/agents/review-probe.js +20 -0
- package/lib/cli.js +79 -1
- package/lib/contracts/cli.d.ts +2216 -15
- package/lib/contracts/cli.js +171 -4
- package/lib/contracts/diagnosis.d.ts +2 -1
- package/lib/contracts/diagnosis.js +1 -0
- package/lib/contracts/events.d.ts +1052 -4
- package/lib/contracts/events.js +94 -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 +2 -0
- package/lib/contracts/index.js +2 -0
- package/lib/contracts/policy.d.ts +27 -1
- package/lib/contracts/policy.js +38 -2
- package/lib/contracts/ports.d.ts +5 -1
- package/lib/contracts/published.d.ts +1398 -2
- package/lib/contracts/published.js +4 -0
- package/lib/contracts/repair-policy.js +5 -0
- package/lib/contracts/report.d.ts +1151 -0
- package/lib/contracts/report.js +401 -0
- package/lib/control/harness.d.ts +486 -7
- package/lib/control/harness.js +86 -1
- package/lib/control/recovery.d.ts +1 -1
- package/lib/control/report-file.d.ts +19 -0
- package/lib/control/report-file.js +85 -0
- package/lib/control/report.d.ts +9 -0
- package/lib/control/report.js +27 -0
- package/lib/engine/engine.d.ts +20 -8
- package/lib/engine/engine.js +73 -7
- 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 +121 -13
- 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/dependency-network.d.ts +42 -0
- package/lib/environment/dependency-network.js +413 -0
- package/lib/environment/lifecycle.d.ts +3 -1
- package/lib/environment/lifecycle.js +23 -4
- package/lib/environment/process.d.ts +12 -1
- package/lib/environment/process.js +52 -0
- package/lib/environment/redaction.d.ts +2 -0
- package/lib/environment/redaction.js +19 -0
- package/lib/explain/state.d.ts +38 -0
- package/lib/explain/state.js +31 -11
- 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 +4 -1
- package/lib/index.js +3 -0
- package/lib/integrations/connector/redact.d.ts +2 -13
- package/lib/integrations/connector/redact.js +2 -21
- package/lib/projections/attempt.d.ts +129 -0
- package/lib/projections/attempt.js +78 -0
- package/lib/projections/index.d.ts +2 -1
- package/lib/projections/index.js +2 -1
- package/lib/projections/stop.d.ts +30 -1
- package/lib/projections/stop.js +59 -24
- package/lib/report/compute.d.ts +72 -0
- package/lib/report/compute.js +1220 -0
- package/lib/report/document.d.ts +27 -0
- package/lib/report/document.js +206 -0
- package/lib/report/format.d.ts +23 -0
- package/lib/report/format.js +53 -0
- package/lib/report/html.d.ts +7 -0
- package/lib/report/html.js +109 -0
- package/lib/report/index.d.ts +4 -0
- package/lib/report/index.js +7 -0
- package/lib/report/markdown.d.ts +7 -0
- package/lib/report/markdown.js +112 -0
- package/lib/storage/document.d.ts +28 -6
- package/lib/storage/sqlite.d.ts +21 -0
- package/lib/storage/sqlite.js +70 -7
- package/lib/verification/gates-at.d.ts +11 -1
- package/lib/verification/gates-at.js +28 -2
- package/lib/verification/gates.d.ts +9 -1
- package/lib/verification/gates.js +20 -0
- package/package.json +5 -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 +455 -0
- package/schemas/stop-diagnosis.schema.json +1 -0
- package/schemas/value-report.schema.json +2542 -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,24 +90,47 @@ 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`
|
|
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]…` | Пакет передачи контекста новой сессии агента |
|
|
105
107
|
|
|
106
108
|
stdout — один JSON (`devcontour-harness/v1alpha1`), диагностика — stderr. Exit
|
|
107
109
|
codes: 0 успех, 2 неверный вход, 3 отказ/блокировка, 4 инфраструктура.
|
|
108
110
|
`HARNESS_CODEX_BIN` и `HARNESS_CLAUDE_BIN` подменяют исполняемые файлы runtime
|
|
109
111
|
— например, fixture executable в тестах (это не живая модель).
|
|
110
112
|
|
|
113
|
+
## Что вы увидите: отчёт
|
|
114
|
+
|
|
115
|
+
`harness report --state D --format html --out report.html` строит по
|
|
116
|
+
каталогу состояния один HTML-файл (или Markdown, или JSON в конверте): что
|
|
117
|
+
дал harness на этом проекте. Сводка — не больше пяти чисел с основанием:
|
|
118
|
+
сколько поручений принято и сколько с первой попытки, сколько вернули
|
|
119
|
+
проверки, ревью или правило области до слияния, срок от согласования до
|
|
120
|
+
приёмки, известный расход на принятое поручение и доля отказов окружения.
|
|
121
|
+
Дальше — разделы о дефектах, автономности, скорости, расходе, окружении,
|
|
122
|
+
неделях, таблица поручений и «Ограничения и неизвестное».
|
|
123
|
+
|
|
124
|
+
Отчёт показывает только наблюдения: счёт и длительности из записанного
|
|
125
|
+
состояния, без «сэкономленных часов» и сравнения «до и после». Неизвестное
|
|
126
|
+
не превращается в ноль («≥ $5.73», «unknown»); процент — от 20 в
|
|
127
|
+
знаменателе, медиана — от 5 значений, меньше трёх принятых поручений —
|
|
128
|
+
«недостаточно данных». Тексты prompt, находок и ошибок, токены и домашний
|
|
129
|
+
каталог в отчёт не попадают; `--no-titles` убирает и заголовки. Тот же
|
|
130
|
+
каталог — те же байты: момент отчёта — последняя метка времени в данных.
|
|
131
|
+
Хост строит тот же отчёт из своего хранилища: `valueReport` из
|
|
132
|
+
`devcontour-harness/report`. Подробно — [ValueReport](docs/contracts.md#valuereport).
|
|
133
|
+
|
|
111
134
|
## Библиотека
|
|
112
135
|
|
|
113
136
|
```js
|
|
@@ -124,6 +147,19 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
|
|
|
124
147
|
`devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
|
|
125
148
|
Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
|
|
126
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
|
+
|
|
157
|
+
## Выпуск 0.1.0-alpha.30
|
|
158
|
+
|
|
159
|
+
Отчёт об эффекте `harness report`, события стадий и `status --detail` для
|
|
160
|
+
наблюдения за попыткой, сетевые отказы установки зависимостей — отказ среды.
|
|
161
|
+
Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.30.md).
|
|
162
|
+
|
|
127
163
|
## Выпуск 0.1.0-alpha.29
|
|
128
164
|
|
|
129
165
|
Проверки под нагрузкой машины стартуют надёжно, а несостоявшийся старт песочницы
|
package/docs/architecture.md
CHANGED
|
@@ -689,6 +689,70 @@ executable. Live smoke — отдельный opt-in с явно заданны
|
|
|
689
689
|
каталогах: srt ищет его через `which` с таймаутом в секунду, и под
|
|
690
690
|
нагрузкой машины такой поиск отказывал до запуска команды. Не найденный
|
|
691
691
|
так shell по-прежнему ищет `which`.
|
|
692
|
+
- **Сеть и реестр при установке зависимостей.** Упавшая установка
|
|
693
|
+
зависимостей — класс `environment` с причиной `dependency-network`, а не
|
|
694
|
+
`gate`, только при всех условиях
|
|
695
|
+
<!-- repo-only -->(`src/environment/dependency-network.ts`)<!-- /repo-only -->:
|
|
696
|
+
- **Команда.** argv закреплён политикой (gate попытки или шаг `prepare`) и
|
|
697
|
+
сам является установкой: `npm install|i|ci|clean-install`, `pnpm
|
|
698
|
+
install|i|fetch`, `yarn [install]`, в том числе через `corepack` (и
|
|
699
|
+
`corepack pnpm@9`), по абсолютному пути и с `.cmd`. До подкоманды —
|
|
700
|
+
только известные опции; `--`, неизвестная опция без `=`, `npm run …`,
|
|
701
|
+
`npx`, `pnpm exec`, shell и собственные скрипты — не установка.
|
|
702
|
+
- **Входы как в базе.** Входы менеджера в проверяемом дереве совпадают с
|
|
703
|
+
базой попытки (`baseSha`): `.npmrc`, `.yarnrc`, `.yarnrc.yml`, pnpmfile,
|
|
704
|
+
`pnpm-workspace.yaml`, lockfiles, `.pnp.*` и все `.gitignore` — побайтно; в
|
|
705
|
+
каждом `package.json` — поля зависимостей, `overrides`, `resolutions`,
|
|
706
|
+
`pnpm`, `packageManager`, `workspaces` и скрипты установки. Файлы дерева
|
|
707
|
+
находит обход файловой системы, а не индекс git: манифест, скрытый
|
|
708
|
+
`.gitignore` или `.git/info/exclude`, менеджер всё равно найдёт по глобу
|
|
709
|
+
workspace. Обход не заходит в `node_modules`, `.git` и копию хранилища
|
|
710
|
+
зависимостей в корне (`.pnpm-store`), ссылки не разыменовывает; каждая
|
|
711
|
+
символическая ссылка дерева должна быть в базе с той же целью. Symlink
|
|
712
|
+
вместо файла, удаление или новый файл — расхождение. Без базы (проверка
|
|
713
|
+
потребителя, `runGatesAt`, lifecycle) классификации нет. На integration
|
|
714
|
+
сверка идёт с той же базой: правки целевой ветки после неё дают
|
|
715
|
+
расхождение, и отказ остаётся `gate`.
|
|
716
|
+
- **База не исполняет кода при установке.** Ни в одном `package.json` базы
|
|
717
|
+
нет скриптов установки (`preinstall`, `install`, `postinstall`,
|
|
718
|
+
`prepublish`, `prepare` и соседних, `dependencies`), нет pnpmfile и
|
|
719
|
+
`.pnp.*`, а `.npmrc`, `.yarnrc*` и `pnpm-workspace.yaml` не ссылаются на
|
|
720
|
+
код (`pnpmfile`, `node-options`, `script-shell`, `yarnPath`, `plugins` и
|
|
721
|
+
подобные). Такой скрипт базы мог бы исполнить исходник кандидата, и
|
|
722
|
+
выводу установки верить было бы нельзя.
|
|
723
|
+
- **Менеджер вышел сам** с кодом 1–127; выход по сигналу или без кода — не
|
|
724
|
+
его отчёт.
|
|
725
|
+
- **Отчёт в формате менеджера.** Заголовок ошибки pnpm (`ERR_PNPM_FETCH_403`,
|
|
726
|
+
`ECONNRESET` в узких пробелах), строка `npm error code …`, строка yarn
|
|
727
|
+
`error An unexpected error occurred: …`. Каждый названный код — сетевой:
|
|
728
|
+
HTTP 403, 407, 408, 429 или 5xx реестра, `FETCH_ERROR`, errno соединения,
|
|
729
|
+
TLS или сертификат. Каждая строка ошибки yarn несёт сетевую подпись. В
|
|
730
|
+
выводе нет признака ошибки проекта: lockfile, нет версии или пакета, 404,
|
|
731
|
+
peer-зависимости, упавший скрипт, целостность. Сетевые слова в выводе
|
|
732
|
+
скриптов, эхо команды npm и предупреждения повтора pnpm не засчитываются.
|
|
733
|
+
|
|
734
|
+
Сообщение начинается с `dependency-network:` и подписи — его показывают
|
|
735
|
+
`explain`, `result` и история попыток. Дальше отказ ведёт себя как любой
|
|
736
|
+
отказ окружения: попытку не тратит, ставит паузу `runtime`, повтор
|
|
737
|
+
восстановлением берёт того же кандидата и заново гоняет проверки, второй
|
|
738
|
+
одинаковый отказ останавливает работу, на поручение действует
|
|
739
|
+
`MAX_NEUTRAL_FAILURES`. Reviewer probe такого gate (с базой попытки) получает
|
|
740
|
+
`error`/`environment`.
|
|
741
|
+
|
|
742
|
+
Почему подделка не проходит. Отказ, причина которого в правке кандидата
|
|
743
|
+
(реестр в `.npmrc`, URL tarball, новый пакет, закрытый прокси, свой
|
|
744
|
+
pnpmfile или скрипт установки), — расхождение входов с базой, и он остаётся
|
|
745
|
+
`gate`: его видит и чинит следующая попытка, а очередь не встаёт. Напечатать
|
|
746
|
+
строки менеджера кандидат может только кодом, который менеджер исполняет при
|
|
747
|
+
установке, — его нет ни в базе, ни в дереве. Скрипт, убивший менеджер,
|
|
748
|
+
оставляет выход по сигналу. Остаётся настоящий отказ сети или реестра на
|
|
749
|
+
входах базы.
|
|
750
|
+
|
|
751
|
+
Отладчик менеджера (`SIGUSR1` открывает инспектор Node) кодом кандидата
|
|
752
|
+
не достижим: при совпадающих входах и базе без кода установки менеджер не
|
|
753
|
+
исполняет кода дерева. Поэтому `--disable-sigusr1` в `NODE_OPTIONS`
|
|
754
|
+
установки не добавляется — он менял бы окружение команды проекта.
|
|
755
|
+
|
|
692
756
|
- **Корень рабочих деревьев.** При состоянии внутри репозитория checkout
|
|
693
757
|
размещается в кэше пользователя вне дерева; хост может задать
|
|
694
758
|
`checkoutRoot`. Корень не должен ни лежать внутри репозитория, состояния
|
package/docs/compatibility.md
CHANGED
|
@@ -148,20 +148,21 @@ Standalone-хост использует `digestOf` (SHA-256 каноничес
|
|
|
148
148
|
|
|
149
149
|
## Сохраняемые форматы
|
|
150
150
|
|
|
151
|
-
| Что | Правило
|
|
152
|
-
| --------------------------------------- |
|
|
153
|
-
| Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи
|
|
154
|
-
| Типы событий журнала | Прежние строки, см. `transactionKinds`
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
158
|
-
|
|
|
159
|
-
|
|
|
160
|
-
|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
|
|
|
151
|
+
| Что | Правило |
|
|
152
|
+
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
153
|
+
| Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
|
|
154
|
+
| Типы событий журнала | Прежние строки, см. `transactionKinds` |
|
|
155
|
+
| События стадий | Тип `attempt.stage` (не выпущено): границы стадий попытки: `started` и не больше одного `finished` на замер `AttemptState.timings` (стадия утратившей владение попытки остаётся открытой); документ состояния и digest политики прежние. Тип, которого читатель не знает, читается как `{type: 'unknown', original}` без нагрузки. Версии до этой событие разбирают строго: после отката ниже неё `events` отказывает на странице с ним (upgrade.md) |
|
|
156
|
+
| Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
|
|
157
|
+
| Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
|
|
158
|
+
| Receipt среды | `environment.json` `version: 1` |
|
|
159
|
+
| Отчёт свойств, договор проверки, корпус | `version: 1` |
|
|
160
|
+
| Хранилище зависимостей | Необязательное `repositories[].dependencyStore`: без поля политика, её digest и каталоги прежние. Каталог `dependency-store` закрыт профилю codex для всех установок, как и другие служебные каталоги; seed другого формата не используется ни как попадание, ни как основа сборки: он пересобирается и вытесняется |
|
|
161
|
+
| Artifacts gates | Необязательное `repositories[].gates[].artifacts`: без поля политика и её digest прежние. Поле `artifactFiles` в evidence gate и в записи совместной проверки необязательно: прежние записи читаются как есть |
|
|
162
|
+
| Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
|
|
163
|
+
| Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения. Таблица `seed_pins` создаётся только при первом обращении хранилища зависимостей |
|
|
164
|
+
| Снимок коннектора | Поля `proof` и `baseline` manifest необязательны: прежние записи читаются как есть. Без `baseline` в конфигурации ревизия, graph digest и context digest те же, что в прежних версиях |
|
|
165
|
+
| Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
|
|
165
166
|
|
|
166
167
|
## Переменные окружения gates
|
|
167
168
|
|