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

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 (55) hide show
  1. package/README.md +22 -3
  2. package/docs/architecture.md +12 -0
  3. package/docs/compatibility.md +21 -18
  4. package/docs/contracts.md +135 -13
  5. package/docs/release-notes/0.1.0-alpha.32.md +33 -0
  6. package/docs/release-notes/0.1.0-alpha.33.md +29 -0
  7. package/docs/release-notes/0.1.0-alpha.34.md +32 -0
  8. package/docs/upgrade.md +137 -0
  9. package/lib/cli.js +2 -2
  10. package/lib/contracts/cli.d.ts +295 -5
  11. package/lib/contracts/events.d.ts +350 -4
  12. package/lib/contracts/events.js +63 -2
  13. package/lib/contracts/failure.d.ts +6 -1
  14. package/lib/contracts/failure.js +5 -1
  15. package/lib/contracts/handoff.d.ts +8 -0
  16. package/lib/contracts/handoff.js +17 -3
  17. package/lib/contracts/published.d.ts +177 -3
  18. package/lib/contracts/report.d.ts +116 -2
  19. package/lib/contracts/report.js +61 -3
  20. package/lib/control/base-move.d.ts +7 -2
  21. package/lib/control/base-move.js +14 -1
  22. package/lib/control/harness.d.ts +44 -8
  23. package/lib/control/harness.js +8 -96
  24. package/lib/control/status.d.ts +235 -0
  25. package/lib/control/status.js +101 -0
  26. package/lib/engine/budget.d.ts +78 -0
  27. package/lib/engine/budget.js +13 -2
  28. package/lib/engine/classify.d.ts +14 -1
  29. package/lib/engine/classify.js +34 -0
  30. package/lib/engine/engine.d.ts +17 -5
  31. package/lib/engine/engine.js +75 -5
  32. package/lib/engine/runner.js +4 -5
  33. package/lib/environment/isolation.d.ts +67 -3
  34. package/lib/environment/isolation.js +148 -5
  35. package/lib/environment/lifecycle.js +1 -1
  36. package/lib/explain/state.d.ts +25 -4
  37. package/lib/explain/state.js +29 -0
  38. package/lib/handoff/index.d.ts +1 -1
  39. package/lib/handoff/markdown.js +4 -2
  40. package/lib/handoff/pack.d.ts +38 -8
  41. package/lib/handoff/pack.js +57 -18
  42. package/lib/index.d.ts +18 -3
  43. package/lib/index.js +18 -2
  44. package/lib/integrations/connector/testing.js +1 -1
  45. package/lib/projections/next.d.ts +3 -1
  46. package/lib/projections/next.js +4 -1
  47. package/lib/projections/stop.d.ts +11 -0
  48. package/lib/projections/stop.js +44 -15
  49. package/lib/report/compute.js +228 -21
  50. package/lib/report/document.js +31 -7
  51. package/lib/verification/gates.js +20 -4
  52. package/package.json +1 -1
  53. package/schemas/handoff-pack.schema.json +6 -0
  54. package/schemas/run-event.schema.json +319 -0
  55. package/schemas/value-report.schema.json +235 -3
@@ -1,7 +1,8 @@
1
1
  import { homedir, tmpdir } from 'node:os';
2
2
  import { dirname, join, relative, sep } from 'node:path';
3
3
  import { createRequire } from 'node:module';
4
- import { writeFile, mkdir } from 'node:fs/promises';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { writeFile, mkdir, mkdtemp, realpath, rm, readdir, lstat, rename } from 'node:fs/promises';
5
6
  import { existsSync, lstatSync, readlinkSync, realpathSync, readdirSync } from 'node:fs';
6
7
  import { spawn } from 'node:child_process';
7
8
  import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
@@ -689,13 +690,153 @@ export function protectedChanges(before, root) {
689
690
  })
690
691
  .map(([path]) => path);
691
692
  }
693
+ /**
694
+ * Предел пути unix-сокета (`sun_path`, вместе с завершающим NUL): 104 байта
695
+ * на macOS, 108 на Linux. srt слушает свои сокеты во временном каталоге
696
+ * процесса (`srt-mux-<pid>-<n>.sock`, `claude-socks-<16 hex>.sock`,
697
+ * `srt-obs-XXXXXX/s<8 hex>.sock`); глубокий TMPDIR делает путь длиннее
698
+ * предела, и srt падает до запуска команды (`listen EINVAL`).
699
+ */
700
+ export const SOCKET_PATH_LIMIT = {
701
+ darwin: 104,
702
+ linux: 108,
703
+ };
704
+ /** Запас под самое длинное имя сокета srt внутри его временного каталога (с разделителем). */
705
+ export const SRT_SOCKET_RESERVE = 48;
706
+ /** Короткая база временного каталога srt, когда TMPDIR процесса слишком глубокий. */
707
+ export const SRT_SHORT_BASE = '/tmp';
708
+ /**
709
+ * База, которую берёт `runGate`; тест подменяет её, чтобы проверить отказ
710
+ * (как `isolationBackend`).
711
+ */
712
+ export const srtTempBase = { short: SRT_SHORT_BASE };
713
+ /** Возраст, после которого брошенный каталог srt убирается при создании нового. */
714
+ export const SRT_STALE_MS = 24 * 60 * 60 * 1000;
715
+ /** Имя своего каталога srt: `dc-srt-<pid создателя>-<суффикс mkdtemp>`. */
716
+ const srtDirName = /^dc-srt-([1-9]\d*)-[A-Za-z0-9]{6}$/;
717
+ const processAlive = (pid) => {
718
+ try {
719
+ process.kill(pid, 0);
720
+ return true;
721
+ }
722
+ catch (error) {
723
+ // EPERM — процесс есть, но чужой: считаем живым.
724
+ return error.code === 'EPERM';
725
+ }
726
+ };
727
+ /** Наибольший pid, который принимает уборка (pid_t — 32-битное со знаком). */
728
+ const MAX_PID = 2 ** 31 - 1;
729
+ /** Префикс каталога srt, переименованного уборкой перед удалением. */
730
+ export const SRT_REMOVING_PREFIX = '.dc-srt-rm-';
731
+ /**
732
+ * Уборка брошенных каталогов srt (controller упал до своей уборки) — по
733
+ * возможности, ошибки не мешают проверке. Удаляется только запись, которая
734
+ * одновременно:
735
+ * - имя `dc-srt-<pid>-XXXXXX`, pid — безопасное целое не больше 2^31−1 и не
736
+ * этот процесс (иначе запись остаётся);
737
+ * - каталог (не symlink, `lstat`) этого пользователя;
738
+ * - ни сам каталог, ни одна запись прямо в нём не менялись дольше
739
+ * `SRT_STALE_MS`. Свежая запись внутри — признак живого srt: процесс srt
740
+ * переживает controller, убитый SIGKILL (pid создателя уже свободен), а
741
+ * контейнеры с общим `/tmp` и своим пространством pid не видят создателя
742
+ * из другого пространства — для них «процесса нет» ничего не доказывает;
743
+ * - процесс-создатель не существует (ESRCH; EPERM — процесс есть, он жив).
744
+ * Повтор pid только оставляет каталог.
745
+ *
746
+ * Удаление без гонки с подменой: каталог сначала переименовывается в
747
+ * `.dc-srt-rm-<uuid>` того же каталога, переименованный путь проверяется
748
+ * снова (каталог, владелец, тот же inode), и только тогда удаляется. Не
749
+ * прошедший повторную проверку остаётся под новым именем; уборка его не
750
+ * трогает, как и остаток после падения между rename и rm.
751
+ */
752
+ export async function sweepStaleSrtDirs(short, now = Date.now()) {
753
+ const uid = process.getuid?.();
754
+ if (uid === undefined)
755
+ return [];
756
+ let names;
757
+ try {
758
+ names = await readdir(short);
759
+ }
760
+ catch {
761
+ return [];
762
+ }
763
+ const fresh = (mtimeMs) => now - mtimeMs < SRT_STALE_MS;
764
+ const removed = [];
765
+ for (const name of names) {
766
+ const pid = Number(srtDirName.exec(name)?.[1]);
767
+ if (!Number.isSafeInteger(pid) || pid < 1 || pid > MAX_PID || pid === process.pid)
768
+ continue;
769
+ const path = join(short, name);
770
+ try {
771
+ const st = await lstat(path);
772
+ if (!st.isDirectory() || st.uid !== uid || fresh(st.mtimeMs))
773
+ continue;
774
+ let recent = false;
775
+ for (const entry of await readdir(path))
776
+ if (fresh((await lstat(join(path, entry))).mtimeMs)) {
777
+ recent = true;
778
+ break;
779
+ }
780
+ if (recent || processAlive(pid))
781
+ continue;
782
+ const moved = join(short, SRT_REMOVING_PREFIX + randomUUID());
783
+ await rename(path, moved);
784
+ const again = await lstat(moved);
785
+ if (!again.isDirectory() || again.uid !== uid || again.ino !== st.ino || again.dev !== st.dev)
786
+ continue;
787
+ await rm(moved, { recursive: true, force: true });
788
+ removed.push(path);
789
+ }
790
+ catch {
791
+ // Уборка по возможности: запись исчезла, нет прав — пропускаем.
792
+ }
793
+ }
794
+ return removed;
795
+ }
796
+ /** Путь каталога оставляет место сокетам srt на этой платформе. */
797
+ export const srtSocketsFit = (dir, platform = process.platform) => {
798
+ const limit = SOCKET_PATH_LIMIT[platform];
799
+ return limit === undefined || Buffer.byteLength(dir) + SRT_SOCKET_RESERVE < limit;
800
+ };
801
+ /**
802
+ * Временный каталог процесса srt. TMPDIR процесса — как есть, если сокеты
803
+ * srt в нём укладываются в предел пути; иначе — свой каталог под
804
+ * `SRT_SHORT_BASE` (`mkdtemp`: новый, `0700`, только владельцу), который
805
+ * вызывающий удаляет после проверки (`created`); перед созданием убираются
806
+ * брошенные каталоги (`sweepStaleSrtDirs`). Если и он не укладывается
807
+ * или не создаётся — `SandboxPolicyError` (отказ среды, `environment`) до
808
+ * запуска, с именем TMPDIR в тексте.
809
+ * Команде внутри передаётся свой scratch, не этот каталог.
810
+ */
811
+ export async function srtTempDir(base = tmpdir(), platform = process.platform, short = srtTempBase.short) {
812
+ if (srtSocketsFit(base, platform))
813
+ return { dir: base, created: false };
814
+ const limit = SOCKET_PATH_LIMIT[platform];
815
+ const refuse = (detail) => new SandboxPolicyError(`Песочница проверки не запустится: путь сокетов sandbox-runtime в TMPDIR ` +
816
+ `(${base}, ${Buffer.byteLength(base)} байт) длиннее предела unix-сокета ` +
817
+ `${limit} байт, а короткий каталог ${short} ${detail}. Задайте более короткий TMPDIR`);
818
+ await sweepStaleSrtDirs(short);
819
+ let dir;
820
+ try {
821
+ dir = await realpath(await mkdtemp(join(short, `dc-srt-${process.pid}-`)));
822
+ }
823
+ catch (error) {
824
+ throw refuse(`недоступен: ${error.message}`);
825
+ }
826
+ if (!srtSocketsFit(dir, platform)) {
827
+ await rm(dir, { recursive: true, force: true });
828
+ throw refuse(`тоже слишком длинный (${dir})`);
829
+ }
830
+ return { dir, created: true };
831
+ }
692
832
  /**
693
833
  * Команда проверки внутри sandbox-runtime.
694
834
  *
695
835
  * Настройки пишутся в файл: srt отказывает, если файл пуст или невалиден, и
696
836
  * не откатывается к умолчаниям. Собственный служебный сокет srt кладёт во
697
- * временный каталог процесса, поэтому srt получает короткий системный
698
- * TMPDIR, а команде внутри передаётся свой scratch.
837
+ * временный каталог процесса, поэтому srt получает TMPDIR, в котором путь
838
+ * сокета укладывается в предел (`srtTempDir`), а команде внутри передаётся
839
+ * свой scratch.
699
840
  *
700
841
  * `cwd` — каталог, из которого запускается srt (см. `protectedWriteDenies`):
701
842
  * на macOS это каталог метки старта, а в рабочий каталог проверки обёртка
@@ -721,7 +862,9 @@ tag = '',
721
862
  * Метку-файл команда может стереть (каталог метки ей открыт на запись), а
722
863
  * напечатанное до неё — нет: токен в выводе доказывает старт.
723
864
  */
724
- token = '') {
865
+ token = '',
866
+ /** Временный каталог процесса srt (`srtTempDir`); по умолчанию TMPDIR процесса. */
867
+ srtTemp = tmpdir()) {
725
868
  if (!/^[a-z0-9]*$/.test(tag))
726
869
  throw new Error('Токен журнала песочницы — только [a-z0-9]');
727
870
  if (!/^[a-z0-9]*$/.test(token))
@@ -757,7 +900,7 @@ token = '') {
757
900
  `TMPDIR=${scratch}`,
758
901
  ...argv,
759
902
  ],
760
- env: { TMPDIR: tmpdir() },
903
+ env: { TMPDIR: srtTemp },
761
904
  // Без явных запретов srt остаётся в рабочем каталоге: его собственный
762
905
  // обязательный запрет действует от него.
763
906
  cwd: denies ? dirname(started) : workdir,
@@ -111,7 +111,7 @@ trustedBase) {
111
111
  })
112
112
  : undefined;
113
113
  if (network)
114
- throw new TaskFailure('environment', dependencyNetworkMessage(execution.redact(network), message));
114
+ throw new TaskFailure('environment', dependencyNetworkMessage(execution.redact(network), message), undefined, 'dependency-network');
115
115
  throw new Error(message);
116
116
  }
117
117
  }
@@ -1,6 +1,25 @@
1
- import type { ExecutionView } from '../contracts/index.ts';
2
- import type { Harness } from '../control/harness.ts';
1
+ import type { ExecutionPolicy, ExecutionView, WorkflowJob } from '../contracts/index.ts';
2
+ import type { Engine } from '../engine/engine.ts';
3
3
  import type { StopInput } from '../projections/stop.ts';
4
+ /**
5
+ * Что читают диагнозы по сохранённому состоянию (`stopInputsOf`) и пакет
6
+ * передачи контекста: движок над хранилищем, политика исполнения и очередь
7
+ * заданий графов — список заданий и решение, продолжит ли задание работу.
8
+ * `Harness` удовлетворяет ему структурно (`workflows` — его `WorkflowQueue`);
9
+ * хост со своим движком передаёт свой адаптер заданий.
10
+ */
11
+ export interface StopSource {
12
+ readonly engine: Engine;
13
+ readonly policy: ExecutionPolicy;
14
+ readonly workflows: {
15
+ /** Задания очереди; диагнозы и пакет читают задания `kind: 'graph'`. */
16
+ list(): readonly WorkflowJob[];
17
+ /** Продолжит ли очередь задание сама (как `WorkflowQueue.continues`). */
18
+ continues(job: WorkflowJob, view: ExecutionView, options?: {
19
+ reconfigureApplies?: boolean;
20
+ }): boolean;
21
+ };
22
+ }
4
23
  export interface StopInputOptions {
5
24
  maxAttempts: number;
6
25
  repairBudget: number;
@@ -13,7 +32,9 @@ export interface StopInputOptions {
13
32
  * для `explain` и `status --detail`. `lifted` — пауза есть, но её снимет run.
14
33
  * Документ не меняется: `control` — прежний объект или его копия.
15
34
  */
16
- export declare function nextRunControl(h: Harness, v: ExecutionView): {
35
+ export declare function nextRunControl(h: {
36
+ readonly engine: Engine;
37
+ }, v: ExecutionView): {
17
38
  control: {
18
39
  paused: boolean;
19
40
  pauseReason?: "runtime" | "operator" | "shutdown" | "base-check" | "reconfigure" | undefined;
@@ -53,4 +74,4 @@ export declare function nextRunControl(h: Harness, v: ExecutionView): {
53
74
  * Первым идёт вход действующей роли controller, затем поручения (кроме
54
75
  * принятых) в порядке состояния.
55
76
  */
56
- export declare function stopInputsOf(h: Harness, options: StopInputOptions): StopInput[];
77
+ export declare function stopInputsOf(h: StopSource, options: StopInputOptions): StopInput[];
@@ -95,11 +95,34 @@ export function stopInputsOf(h, options) {
95
95
  for (const w of works)
96
96
  groupOf(w.graphId, w);
97
97
  const everyGroup = new Map([...groups.values()].flatMap((g) => [...g]));
98
+ // Незавершённые работы, которые прямо ждут отменённую: только их и
99
+ // перепланирует replan-dependents. Ждущая через отменённую же
100
+ // промежуточную — забота диагноза той; через принятую — не ждёт вовсе.
101
+ const openDependentsOf = (id) => works
102
+ .filter((w) => w.status !== 'done' &&
103
+ w.status !== 'cancelled' &&
104
+ w.order.dependsOn.includes(id) &&
105
+ !external(w.graphId).has(id))
106
+ .map((w) => w.id);
98
107
  for (const work of works) {
99
108
  if (work.status === 'done')
100
109
  continue;
101
110
  if (options.workId !== undefined && work.id !== options.workId)
102
111
  continue;
112
+ // Отменённая (или упавшая отменой) — решение, только пока её ждут.
113
+ const openDependents = work.status === 'cancelled' ||
114
+ (work.status === 'failed' && work.failureKind === 'cancelled')
115
+ ? openDependentsOf(work.id)
116
+ : undefined;
117
+ // Отменённая без ждущих — не остановка доски: в общий explain и пакет
118
+ // не входит (как принятая); explain этой работы её показывает. Упавшая
119
+ // отменой остаётся открытой работой: её диагноз (действия нет) нужен
120
+ // строке поручения в пакете.
121
+ if (work.status === 'cancelled' &&
122
+ openDependents &&
123
+ !openDependents.length &&
124
+ options.workId === undefined)
125
+ continue;
103
126
  const attempts = v.attempts(work.id);
104
127
  const last = attempts.filter((a) => a.status !== 'active').at(-1);
105
128
  const kind = work.failureKind ?? 'unknown';
@@ -163,6 +186,12 @@ export function stopInputsOf(h, options) {
163
186
  ...(work.recovery ? { recovery: { status: work.recovery.status } } : {}),
164
187
  ...(waitingOn.length ? { waitingOn } : {}),
165
188
  ...(approvalStale ? { approvalStale } : {}),
189
+ ...(openDependents ? { openDependents } : {}),
190
+ ...((stoppedBy) => (stoppedBy ? { repairStoppedBy: stoppedBy } : {}))(
191
+ // Отмена в группе останавливает её восстановление: сёстрам — почему.
192
+ work.status === 'failed' && work.failureKind !== 'cancelled' && !work.recovery && job
193
+ ? works.find((w) => w.graphId === work.graphId && w.status === 'cancelled')?.id
194
+ : undefined),
166
195
  ...((live) => live && live.state !== 'active'
167
196
  ? {
168
197
  liveness: {
@@ -1,2 +1,2 @@
1
- export { handoffPack, type HandoffOptions } from './pack.ts';
1
+ export { handoffPack, type HandoffOptions, type HandoffSource } from './pack.ts';
2
2
  export { handoffMarkdown } from './markdown.ts';
@@ -1,4 +1,4 @@
1
- import { HANDOFF_LIMITS, HANDOFF_MAX_BYTES } from "../contracts/handoff.js";
1
+ import { HANDOFF_LIMITS } from "../contracts/handoff.js";
2
2
  /** Ячейка таблицы Markdown: одна строка, без разделителей колонок. */
3
3
  const cell = (s) => String(s ?? '—')
4
4
  .replace(/\s+/g, ' ')
@@ -32,7 +32,7 @@ export function handoffMarkdown(pack) {
32
32
  `статусы: ${s.byStatus.map((b) => `${b.status} ${b.count}`).join(', ') || '—'}. ` +
33
33
  `Пределы: попыток ${pack.limits.maxAttempts}, восстановлений группы ${pack.limits.repairBudget}.` +
34
34
  (pack.truncated.bySize
35
- ? ` Пакет урезан до ${Math.round(HANDOFF_MAX_BYTES / 1024)} КБ: часть записей отброшена (см. «не вошли»).`
35
+ ? ' Пакет урезан по пределу размера: часть записей отброшена (см. «не вошли»).'
36
36
  : ''), '', '## Следующий шаг', '', `- **${who(pack.next.actor)}: ${pack.next.action}**` +
37
37
  (pack.next.workId ? ` — ${pack.next.workId}` : '') +
38
38
  (pack.next.code ? ` (${pack.next.code})` : '') +
@@ -133,6 +133,8 @@ export function handoffMarkdown(pack) {
133
133
  out.push(...more(pack.truncated.budgets, 'бюджетов'));
134
134
  if (pack.truncated.budgetsWithin)
135
135
  out.push(`Бюджеты поручений в пределах и без расхода не показаны: ${pack.truncated.budgetsWithin}.`);
136
+ if (pack.truncated.budgetsShared)
137
+ out.push(`Бюджеты поручений, весь расход которых — вызовы о их группе (ревью и проверка плана), не показаны: ${pack.truncated.budgetsShared}; этот расход учтён один раз — в строках группы и total.`);
136
138
  }
137
139
  if (pack.repairs.length) {
138
140
  out.push('', 'Восстановления заданий:');
@@ -1,5 +1,5 @@
1
1
  import { type HandoffPack } from '../contracts/handoff.ts';
2
- import type { Harness } from '../control/harness.ts';
2
+ import { type StopSource } from '../explain/state.ts';
3
3
  export interface HandoffOptions {
4
4
  /** Только этот граф; нет — вся доска. */
5
5
  graphId?: string;
@@ -13,7 +13,31 @@ export interface HandoffOptions {
13
13
  * controller), не маскируется — передайте свою маску.
14
14
  */
15
15
  redact?: (text: string) => string;
16
+ /**
17
+ * Предел пакета в байтах UTF-8: целое от `HANDOFF_MIN_BYTES` до
18
+ * `HANDOFF_MAX_BYTES` (по умолчанию). Хост с меньшим пределом ответа
19
+ * получает тот же порядок отбрасывания и те же счётчики `truncated`, что и
20
+ * при пределе по умолчанию; иное значение — отказ `INVALID_INPUT`.
21
+ * Уложиться не гарантируется: неотбрасываемые записи могут быть больше
22
+ * предела. `truncated.bySize` значит «записи отброшены», а не «уложился»:
23
+ * размер результата хост проверяет сам.
24
+ */
25
+ maxBytes?: number;
26
+ /**
27
+ * Что укладывается в `maxBytes`: `json` (по умолчанию) — сериализованный
28
+ * пакет; `markdown` — и JSON, и `handoffMarkdown(pack)`, для хоста, который
29
+ * отдаёт пакет Markdown. Свой раздел хост учитывает, уменьшая `maxBytes`.
30
+ */
31
+ measure?: 'json' | 'markdown';
16
32
  }
33
+ /**
34
+ * Что читает пакет: движок над хранилищем (`read`, `clock`, блокировки,
35
+ * бюджеты), политика исполнения и очередь заданий графов (`list`,
36
+ * `continues`). `Harness` удовлетворяет ему структурно; хост со своим
37
+ * `Engine` передаёт `{ engine, policy, workflows }` со своим адаптером
38
+ * заданий — экземпляр `Harness` не нужен.
39
+ */
40
+ export type HandoffSource = StopSource;
17
41
  /**
18
42
  * Строка не длиннее `n` code units и «…»; суррогатная пара не разрывается.
19
43
  * В отличие от `clipText`, предел не может разрезать символ вне BMP.
@@ -36,14 +60,20 @@ export declare function clipSafe(text: string, n: number): string;
36
60
  * Весь пакет читается одним снимком хранилища: status, диагнозы и задания
37
61
  * графов — вложенные чтения внутри одного `read`.
38
62
  *
39
- * Пакет не больше `HANDOFF_MAX_BYTES` в UTF-8: при превышении записи
40
- * отбрасываются в порядке «намерения с конца, старые провалы, поручения без
41
- * решения, остановки без решения, остальные поручения и остановки» и
42
- * учитываются в `truncated`; отказа по размеру нет.
63
+ * Пакет не больше `maxBytes` (по умолчанию `HANDOFF_MAX_BYTES`) в UTF-8: при
64
+ * превышении записи отбрасываются в порядке «намерения с конца, старые
65
+ * провалы, поручения без решения, остановки без решения, незавершённые
66
+ * попытки, остальные поручения и остановки, строки бюджетов» и учитываются
67
+ * в `truncated`; отказа по размеру нет. Сводка, очередь, идущие попытки,
68
+ * задания и следующий шаг не отбрасываются: предел для них — лучшее
69
+ * усилие.
70
+ *
71
+ * Источник — `Harness` или любой `HandoffSource` хоста.
43
72
  */
44
- export declare function handoffPack(h: Harness, options?: HandoffOptions): HandoffPack;
73
+ export declare function handoffPack(h: HandoffSource, options?: HandoffOptions): HandoffPack;
45
74
  /**
46
75
  * Предел размера в байтах UTF-8: записи отбрасываются в фиксированном
47
- * порядке, пока пакет не уложится; каждая — в `truncated`.
76
+ * порядке, пока пакет не уложится; каждая — в `truncated`. С `markdown`
77
+ * мерой служит больший из размеров JSON и `handoffMarkdown(pack)`.
48
78
  */
49
- export declare function fitPack(pack: HandoffPack, maxBytes?: number): HandoffPack;
79
+ export declare function fitPack(pack: HandoffPack, maxBytes?: number, measure?: 'json' | 'markdown'): HandoffPack;
@@ -1,7 +1,11 @@
1
- import { HANDOFF_LIMITS, HANDOFF_MAX_BYTES, HANDOFF_VERSION, handoffPackSchema, } from "../contracts/handoff.js";
1
+ import { HANDOFF_LIMITS, HANDOFF_MAX_BYTES, HANDOFF_MIN_BYTES, HANDOFF_VERSION, handoffPackSchema, } from "../contracts/handoff.js";
2
2
  import { HarnessError } from "../contracts/errors.js";
3
+ import { statusOf } from "../control/status.js";
4
+ import { budgetBlocks, ownWorkRecords } from "../engine/budget.js";
5
+ import { callRecords } from "../engine/usage.js";
3
6
  import { policySecrets, redactor } from "../environment/redaction.js";
4
7
  import { stopInputsOf } from "../explain/state.js";
8
+ import { handoffMarkdown } from "./markdown.js";
5
9
  import { activeStatuses } from "../projections/enums.js";
6
10
  import { nextAction } from "../projections/next.js";
7
11
  import { explainStop, stopCodeOf } from "../projections/stop.js";
@@ -45,15 +49,33 @@ const actorRank = (d) => (!isDecision(d) ? 2 : d.actor === 'user' ? 0 : 1);
45
49
  * Весь пакет читается одним снимком хранилища: status, диагнозы и задания
46
50
  * графов — вложенные чтения внутри одного `read`.
47
51
  *
48
- * Пакет не больше `HANDOFF_MAX_BYTES` в UTF-8: при превышении записи
49
- * отбрасываются в порядке «намерения с конца, старые провалы, поручения без
50
- * решения, остановки без решения, остальные поручения и остановки» и
51
- * учитываются в `truncated`; отказа по размеру нет.
52
+ * Пакет не больше `maxBytes` (по умолчанию `HANDOFF_MAX_BYTES`) в UTF-8: при
53
+ * превышении записи отбрасываются в порядке «намерения с конца, старые
54
+ * провалы, поручения без решения, остановки без решения, незавершённые
55
+ * попытки, остальные поручения и остановки, строки бюджетов» и учитываются
56
+ * в `truncated`; отказа по размеру нет. Сводка, очередь, идущие попытки,
57
+ * задания и следующий шаг не отбрасываются: предел для них — лучшее
58
+ * усилие.
59
+ *
60
+ * Источник — `Harness` или любой `HandoffSource` хоста.
52
61
  */
53
62
  export function handoffPack(h, options = {}) {
54
- return h.engine.read(() => build(h, options));
63
+ const maxBytes = options.maxBytes ?? HANDOFF_MAX_BYTES;
64
+ if (!Number.isInteger(maxBytes) || maxBytes < HANDOFF_MIN_BYTES || maxBytes > HANDOFF_MAX_BYTES)
65
+ throw new HarnessError('INVALID_INPUT', `maxBytes ${maxBytes}: нужно целое от ${HANDOFF_MIN_BYTES} до ${HANDOFF_MAX_BYTES}`, [
66
+ {
67
+ path: ['maxBytes'],
68
+ message: `${maxBytes} вне ${HANDOFF_MIN_BYTES}..${HANDOFF_MAX_BYTES}`,
69
+ },
70
+ ]);
71
+ const measure = options.measure ?? 'json';
72
+ if (measure !== 'json' && measure !== 'markdown')
73
+ throw new HarnessError('INVALID_INPUT', `measure ${String(measure)}: json или markdown`, [
74
+ { path: ['measure'], message: String(measure) },
75
+ ]);
76
+ return h.engine.read(() => build(h, options, maxBytes, measure));
55
77
  }
56
- function build(h, options) {
78
+ function build(h, options, maxBytes, measure) {
57
79
  const { graphId } = options;
58
80
  const intentions = (options.intentions ?? []).map((s) => s.trim()).filter(Boolean);
59
81
  if (intentions.length > HANDOFF_LIMITS.intentions)
@@ -62,7 +84,7 @@ function build(h, options) {
62
84
  /** Текст из хранилища: маска секретов и предел поля. */
63
85
  const text = (s, n = HANDOFF_LIMITS.text) => (s === undefined ? undefined : clipSafe(plainText(redact(s)), n));
64
86
  const name = (s) => text(s, HANDOFF_LIMITS.name);
65
- const status = h.status(graphId, { detail: true });
87
+ const status = statusOf(h, graphId, { detail: true });
66
88
  if (graphId !== undefined && !status.graphs.length)
67
89
  throw new HarnessError('NOT_FOUND', 'Граф не найден: ' + graphId);
68
90
  const detail = status.detail;
@@ -74,7 +96,11 @@ function build(h, options) {
74
96
  const read = h.engine.read((v) => {
75
97
  const works = v.works(graphId);
76
98
  const attempts = works.flatMap((w) => v.attempts(w.id));
77
- return { works, attempts };
99
+ // Поручения со своими вызовами: строка бюджета поручения, весь расход
100
+ // которого — вызовы о его группе, повторяла бы строку группы N раз.
101
+ const calls = callRecords(v);
102
+ const ownSpend = new Set(works.filter((w) => ownWorkRecords(v, calls, w.id).length > 0).map((w) => w.id));
103
+ return { works, attempts, ownSpend };
78
104
  });
79
105
  const byId = new Map(read.works.map((w) => [w.id, w]));
80
106
  const title = (id) => text(byId.get(id)?.order.title ?? id);
@@ -180,6 +206,7 @@ function build(h, options) {
180
206
  status: w.status,
181
207
  attempt: w.attempt,
182
208
  maxAttempts,
209
+ ...opt('failureKind', w.failureKind),
183
210
  ...opt('hold', w.hold),
184
211
  ...opt('recovery', w.recovery),
185
212
  });
@@ -290,17 +317,24 @@ function build(h, options) {
290
317
  ...opt('action', q.action),
291
318
  };
292
319
  // Бюджеты: общий и групп этого графа — всегда; поручений — только с
293
- // расходом или не в пределах; затем общий предел строк.
320
+ // расходом или не в пределах и только со своими вызовами (расход вызовов о
321
+ // группе — один, его показывают строки группы и total); затем общий предел строк.
294
322
  const relevant = (status.budgets?.budgets ?? []).filter((b) => b.scope.kind === 'total'
295
323
  ? true
296
324
  : b.scope.kind === 'group'
297
325
  ? graphId === undefined || b.scope.id === graphId
298
326
  : b.scope.id !== undefined && byId.has(b.scope.id));
299
- const shown = relevant
300
- .filter((b) => b.scope.kind !== 'work' ||
327
+ const listed = relevant.filter((b) => b.scope.kind !== 'work' ||
301
328
  b.state !== 'within' ||
302
329
  b.reportedUsd + b.estimatedUsd > 0 ||
303
- b.unknownCalls + b.unfinishedCalls + b.abandonedCalls > 0)
330
+ b.unknownCalls + b.unfinishedCalls + b.abandonedCalls > 0);
331
+ // Строка, которая держит выдачу поручения, остаётся: это его ограничение.
332
+ const sharedOnly = (b) => b.scope.kind === 'work' &&
333
+ b.uncoveredRuns === 0 &&
334
+ !read.ownSpend.has(b.scope.id) &&
335
+ !budgetBlocks(b.state, status.budgets?.onUnknown);
336
+ const shown = listed
337
+ .filter((b) => !sharedOnly(b))
304
338
  .map((b, i) => ({ b, i }))
305
339
  .sort((x, y) => (x.b.scope.kind === 'work' ? 1 : 0) - (y.b.scope.kind === 'work' ? 1 : 0) || x.i - y.i)
306
340
  .map(({ b }) => b);
@@ -377,23 +411,28 @@ function build(h, options) {
377
411
  failures: failed.length - failures.length,
378
412
  unfinished: unfinishedAll.length - unfinished.length,
379
413
  budgets: shown.length - budgetEntries.length,
380
- budgetsWithin: relevant.length - shown.length,
414
+ budgetsWithin: relevant.length - listed.length,
415
+ budgetsShared: listed.length - shown.length,
381
416
  repairs: repairsAll.length - repairs.length,
382
417
  intentions: cleanIntentions.filter((s, i) => s !== clippedIntentions[i]).length,
383
418
  intentionsDropped: 0,
384
419
  bySize: false,
385
420
  },
386
421
  };
387
- return handoffPackSchema.parse(fitPack(pack));
422
+ return handoffPackSchema.parse(fitPack(pack, maxBytes, measure));
388
423
  }
389
424
  /** Решение в строке поручения или в остановке. */
390
425
  const decides = (n) => isDecision(n);
391
426
  /**
392
427
  * Предел размера в байтах UTF-8: записи отбрасываются в фиксированном
393
- * порядке, пока пакет не уложится; каждая — в `truncated`.
428
+ * порядке, пока пакет не уложится; каждая — в `truncated`. С `markdown`
429
+ * мерой служит больший из размеров JSON и `handoffMarkdown(pack)`.
394
430
  */
395
- export function fitPack(pack, maxBytes = HANDOFF_MAX_BYTES) {
396
- const size = () => Buffer.byteLength(JSON.stringify(pack));
431
+ export function fitPack(pack, maxBytes = HANDOFF_MAX_BYTES, measure = 'json') {
432
+ const json = () => Buffer.byteLength(JSON.stringify(pack));
433
+ const size = measure === 'markdown'
434
+ ? () => Math.max(json(), Buffer.byteLength(handoffMarkdown(pack)))
435
+ : json;
397
436
  const t = pack.truncated;
398
437
  const dropLast = (list, keep = () => false) => {
399
438
  for (let i = list.length - 1; i >= 0; i--)
package/lib/index.d.ts CHANGED
@@ -61,7 +61,14 @@ export { dependencyStoreRoot, materializeStore, type StoreContext, type StoreRec
61
61
  export { explicitPrerequisites, gatePrerequisites, orderedScope, standaloneScope, } from './verification/gate-scope.ts';
62
62
  export { requirementProof, uncoveredGates, unprovenReason } from './verification/proof.ts';
63
63
  export { ReviewProbes, probeLimits, observeReproductions } from './agents/review-probe.ts';
64
- export { composeRedactors, outputRedactor, redactDeep, redactError, redactor, type Redactor, } from './environment/redaction.ts';
64
+ export { composeRedactors, outputRedactor,
65
+ /**
66
+ * Значения секретов политики (`secrets`-карты на любом уровне) из
67
+ * окружения процесса — маска пакета передачи контекста и коннектора по
68
+ * умолчанию. Хост, составляющий свою маску (`composeRedactors`), берёт
69
+ * секреты политики этим же обходом.
70
+ */
71
+ policySecrets, redactDeep, redactError, redactor, type Redactor, } from './environment/redaction.ts';
65
72
  export { hostGitArgs } from './environment/process.ts';
66
73
  export { UntrustedCheckoutError, assertTrustedCheckout, forgetWorktree, gitHardening, rememberWorktree, resetGitTrust, worktreeAddPath, worktreeKey, } from './environment/git-trust.ts';
67
74
  /**
@@ -76,10 +83,18 @@ export { TaskFailure, failureFingerprint, repairPolicy, MAX_NEUTRAL_FAILURES, ty
76
83
  export * from './projections/index.ts';
77
84
  export * from './report/index.ts';
78
85
  export { collectReportInput } from './control/report.ts';
79
- export { handoffPack, handoffMarkdown, type HandoffOptions } from './handoff/index.ts';
86
+ /**
87
+ * Запись файла отчёта (`harness report --out`): во временный файл каталога
88
+ * цели и rename, без записи сквозь symlink и жёсткие ссылки, вне каталога
89
+ * состояния; новый файл — `0600`. Использует `node:fs`, поэтому только в
90
+ * корне пакета, а не в `./report` (тот без `node:*`).
91
+ */
92
+ export { REPORT_FILE_MODE, writeReportFile, type ReportFileIo } from './control/report-file.ts';
93
+ export { handoffPack, handoffMarkdown, type HandoffOptions, type HandoffSource, } from './handoff/index.ts';
94
+ export { statusOf, type StatusSource } from './control/status.ts';
80
95
  export { inspectPath, checkDestination, listRegularFiles, planFileWrites, applyFileWrites, type FileConflict, type FileIntent, type FileWriteInput, type FilePlanEntry, type FilePlan, } from './setup/files.ts';
81
96
  export { initProject, readProjectManifest, defaultStateDir, projectIdOf, type InitOptions, type InitData, } from './init/project.ts';
82
97
  export { diagnoseState, type DiagnoseOptions } from './explain/diagnose.ts';
83
- export { stopInputsOf, type StopInputOptions } from './explain/state.ts';
98
+ export { stopInputsOf, type StopInputOptions, type StopSource } from './explain/state.ts';
84
99
  export * from './planning/index.ts';
85
100
  export * from './catalog/index.ts';
package/lib/index.js CHANGED
@@ -61,7 +61,14 @@ export { dependencyStoreRoot, materializeStore, } from "./verification/dependenc
61
61
  export { explicitPrerequisites, gatePrerequisites, orderedScope, standaloneScope, } from "./verification/gate-scope.js";
62
62
  export { requirementProof, uncoveredGates, unprovenReason } from "./verification/proof.js";
63
63
  export { ReviewProbes, probeLimits, observeReproductions } from "./agents/review-probe.js";
64
- export { composeRedactors, outputRedactor, redactDeep, redactError, redactor, } from "./environment/redaction.js";
64
+ export { composeRedactors, outputRedactor,
65
+ /**
66
+ * Значения секретов политики (`secrets`-карты на любом уровне) из
67
+ * окружения процесса — маска пакета передачи контекста и коннектора по
68
+ * умолчанию. Хост, составляющий свою маску (`composeRedactors`), берёт
69
+ * секреты политики этим же обходом.
70
+ */
71
+ policySecrets, redactDeep, redactError, redactor, } from "./environment/redaction.js";
65
72
  // Git хоста над checkout, где исполнялся чужой код: хост, запускающий свой
66
73
  // git над теми же деревьями, сверяет репозиторий теми же правилами.
67
74
  export { hostGitArgs } from "./environment/process.js";
@@ -80,7 +87,16 @@ export { TaskFailure, failureFingerprint, repairPolicy, MAX_NEUTRAL_FAILURES, }
80
87
  export * from "./projections/index.js";
81
88
  export * from "./report/index.js";
82
89
  export { collectReportInput } from "./control/report.js";
83
- export { handoffPack, handoffMarkdown } from "./handoff/index.js";
90
+ /**
91
+ * Запись файла отчёта (`harness report --out`): во временный файл каталога
92
+ * цели и rename, без записи сквозь symlink и жёсткие ссылки, вне каталога
93
+ * состояния; новый файл — `0600`. Использует `node:fs`, поэтому только в
94
+ * корне пакета, а не в `./report` (тот без `node:*`).
95
+ */
96
+ export { REPORT_FILE_MODE, writeReportFile } from "./control/report-file.js";
97
+ export { handoffPack, handoffMarkdown, } from "./handoff/index.js";
98
+ // Состояние доски над движком и политикой хоста (`Harness.status` — та же функция).
99
+ export { statusOf } from "./control/status.js";
84
100
  export { inspectPath, checkDestination, listRegularFiles, planFileWrites, applyFileWrites, } from "./setup/files.js";
85
101
  export { initProject, readProjectManifest, defaultStateDir, projectIdOf, } from "./init/project.js";
86
102
  export { diagnoseState } from "./explain/diagnose.js";
@@ -1519,7 +1519,7 @@ export function connectorSuite(backend, options = {}) {
1519
1519
  ...(variant === 'reviewer' ? { reviewer: 'reject' } : {}),
1520
1520
  ...(variant === 'cancel'
1521
1521
  ? {
1522
- onWriter: (request) => void opened.h.engine.cancel(request.subject.workId, 'отмена человеком'),
1522
+ onWriter: (request) => void opened.h.engine.cancel(request.subject.workId, 'отмена человеком', 'operator'),
1523
1523
  }
1524
1524
  : {}),
1525
1525
  });
@@ -1,11 +1,13 @@
1
1
  import type { PropertyRecovery } from '../contracts/execution.ts';
2
- import { type Actor, type NextAction, type WorkStatus } from './enums.ts';
2
+ import { type Actor, type FailureKind, type NextAction, type WorkStatus } from './enums.ts';
3
3
  export declare const nextSteps: readonly ["accepted", "cancelled", "recovery-awaiting-lead", "recovery-analyzing", "recovery-applying", "recovery-retry-allowed", "recovery-retrying", "recovery-awaiting-user", "recovery-stopped", "corpus-adoption", "held", "plan-review", "attempt-running", "retry-within-budget", "attempts-exhausted", "awaiting-claim"];
4
4
  export type NextStep = (typeof nextSteps)[number];
5
5
  export interface NextInput {
6
6
  status: WorkStatus;
7
7
  attempt: number;
8
8
  maxAttempts: number;
9
+ /** Класс отказа упавшей работы: отмену движок не повторяет. */
10
+ failureKind?: FailureKind;
9
11
  hold?: {
10
12
  operation: string;
11
13
  };