owenloop 0.5.27 → 0.5.29

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 (53) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/dist/packages/work/src/agent/brief.d.ts +10 -0
  3. package/dist/packages/work/src/agent/brief.js +38 -0
  4. package/dist/packages/work/src/agent/loop.js +4 -0
  5. package/dist/packages/work/src/consumed-verifier.d.ts +22 -2
  6. package/dist/packages/work/src/consumed-verifier.js +131 -12
  7. package/dist/packages/work/src/contained-path.d.ts +18 -0
  8. package/dist/packages/work/src/contained-path.js +42 -0
  9. package/dist/packages/work/src/exec/instructions.js +43 -3
  10. package/dist/packages/work/src/harness/claude.js +21 -0
  11. package/dist/packages/work/src/harness/codex.js +29 -0
  12. package/dist/packages/work/src/harness/contract.d.ts +26 -0
  13. package/dist/packages/work/src/hold/mcp.d.ts +3 -40
  14. package/dist/packages/work/src/hold/mcp.js +121 -2
  15. package/dist/packages/work/src/hub/client.d.ts +10 -1
  16. package/dist/packages/work/src/hub/client.js +23 -0
  17. package/dist/packages/work/src/hub/types.d.ts +45 -0
  18. package/dist/packages/work/src/roles/shift.js +7 -1
  19. package/dist/packages/work/src/settings/settings.d.ts +12 -1
  20. package/dist/packages/work/src/settings/settings.js +7 -0
  21. package/dist/packages/work/src/shift/disk-floor.d.ts +107 -0
  22. package/dist/packages/work/src/shift/disk-floor.js +148 -0
  23. package/dist/packages/work/src/shift/host-preflight.d.ts +85 -0
  24. package/dist/packages/work/src/shift/host-preflight.js +112 -0
  25. package/dist/packages/work/src/shift/loop.d.ts +18 -0
  26. package/dist/packages/work/src/shift/loop.js +179 -7
  27. package/dist/packages/work/src/shift/protocol.d.ts +62 -1
  28. package/dist/packages/work/src/shift/runtime.d.ts +2 -0
  29. package/dist/packages/work/src/shift/runtime.js +17 -0
  30. package/dist/packages/work/src/submit-file.d.ts +3 -2
  31. package/dist/packages/work/src/submit-file.js +6 -22
  32. package/dist/src/crypto/records.d.ts +1 -0
  33. package/dist/src/crypto/records.js +1 -0
  34. package/dist/src/crypto/verify-consumed.d.ts +16 -1
  35. package/dist/src/crypto/verify-consumed.js +21 -6
  36. package/dist/src/schemas/index.d.ts +23 -0
  37. package/dist/src/schemas/order.v1.schema.json +14 -0
  38. package/dist/src/store/index.d.ts +1 -1
  39. package/dist/src/store/instruction-source.d.ts +15 -0
  40. package/dist/src/store/instruction-source.js +64 -4
  41. package/dist/src/store/types.d.ts +6 -2
  42. package/dist/src/store/types.js +5 -1
  43. package/dist/src/types.d.ts +11 -0
  44. package/docs/bundles.md +5 -1
  45. package/docs/cli.md +8 -5
  46. package/docs/crypto.md +46 -0
  47. package/docs/shift-logs.md +64 -7
  48. package/docs/wire-contracts.md +15 -2
  49. package/package.json +1 -1
  50. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  51. package/plugins/claude-code/plugin/.mcp.json +1 -1
  52. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  53. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
@@ -4,7 +4,7 @@
4
4
  * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
5
  * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
6
  * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
- * server exposes four bare tools the model uses to do its order:
7
+ * server exposes five bare tools the model uses to do its order:
8
8
  * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
9
  * this holder is bound to. No ids are arguments — they came in on argv, never
10
10
  * through the model.
@@ -23,6 +23,13 @@
23
23
  * until the stall cap). `ask` holds the artifact with no counter movement
24
24
  * and surfaces the question to an operator, who answers with
25
25
  * `owenloop retry <workflow> <path> --text "<answer>"`.
26
+ * - `put_file_artifact` → store a file the step produced and get back the small
27
+ * JSON envelope that names it. An artifact value lives in the org's database
28
+ * and is size-capped for good reason, but a rendered video or a screenshot is
29
+ * an artifact too. Rather than let a step choose between truncating its own
30
+ * output and base64-inflating it past the cap, the bytes go to blob storage
31
+ * and the envelope — hash, size, content type — goes in the value, where a
32
+ * def's ordinary JSON Schema can still constrain it.
26
33
  *
27
34
  * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
28
35
  * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
@@ -35,15 +42,55 @@
35
42
  * its own — so a unit test drives the tools with a fake hub and a scriptable
36
43
  * clock. The role (`src/roles/hold.ts`) owns the real stdin/stdout pump.
37
44
  */
45
+ import { readFile } from 'node:fs/promises';
46
+ import { basename, extname } from 'node:path';
38
47
  import { textResult } from "../mcp/server.js";
39
48
  import { buildSubmitProof } from "../submit-proof.js";
40
49
  import { readSubmitValueFile } from "../submit-file.js";
50
+ import { resolveContainedPath } from "../contained-path.js";
41
51
  import { normalizeSubmitValue } from "../submit-value.js";
42
52
  import { createHoldLoop } from "./loop.js";
43
- export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject', 'ask'];
53
+ export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject', 'ask', 'put_file_artifact'];
44
54
  function errMsg(e) {
45
55
  return e instanceof Error ? e.message : String(e);
46
56
  }
57
+ /**
58
+ * Extension-to-MIME map for `put_file_artifact`'s optional `contentType`.
59
+ *
60
+ * Deliberately short. This is a convenience for the common case, not a content
61
+ * sniffer: the map covers what a step actually renders — images, video, audio,
62
+ * documents, archives, text — and everything else falls through to
63
+ * `application/octet-stream`, which is the honest answer for bytes whose type
64
+ * this process did not determine. A step that knows better passes `contentType`
65
+ * explicitly and this map is never consulted.
66
+ */
67
+ const CONTENT_TYPE_BY_EXTENSION = {
68
+ '.png': 'image/png',
69
+ '.jpg': 'image/jpeg',
70
+ '.jpeg': 'image/jpeg',
71
+ '.gif': 'image/gif',
72
+ '.webp': 'image/webp',
73
+ '.svg': 'image/svg+xml',
74
+ '.avif': 'image/avif',
75
+ '.mp4': 'video/mp4',
76
+ '.webm': 'video/webm',
77
+ '.mov': 'video/quicktime',
78
+ '.mp3': 'audio/mpeg',
79
+ '.wav': 'audio/wav',
80
+ '.pdf': 'application/pdf',
81
+ '.zip': 'application/zip',
82
+ '.tar': 'application/x-tar',
83
+ '.gz': 'application/gzip',
84
+ '.json': 'application/json',
85
+ '.txt': 'text/plain',
86
+ '.md': 'text/markdown',
87
+ '.csv': 'text/csv',
88
+ '.html': 'text/html',
89
+ '.log': 'text/plain',
90
+ };
91
+ function guessContentType(path) {
92
+ return CONTENT_TYPE_BY_EXTENSION[extname(path).toLowerCase()] ?? 'application/octet-stream';
93
+ }
47
94
  /** A lean, model-facing view of the order packet. */
48
95
  function orderView(res) {
49
96
  return { workflow: res.workflow, run: res.run, order: res.order, text: res.text };
@@ -342,11 +389,83 @@ export function createHoldMcp(deps) {
342
389
  }
343
390
  },
344
391
  };
392
+ const putFileArtifactTool = {
393
+ name: 'put_file_artifact',
394
+ description: 'Store a FILE you produced (image, video, PDF, archive, log, any bytes) and get back a small JSON envelope that names it. Use this whenever an owed output IS a file, or CONTAINS one: upload the file, then call submit with the envelope as the value, or embedded inside your value, e.g. {"summary": "...", "render": <envelope>}. The bytes are stored outside the database, so a large asset does not count against the artifact value size limit — the envelope is what the workflow stores, schema-checks and shows a judge. Do NOT base64 a file into a submit value; upload it here instead.',
395
+ inputSchema: {
396
+ type: 'object',
397
+ required: ['file'],
398
+ properties: {
399
+ file: {
400
+ type: 'string',
401
+ description: 'Path to the file to store. Relative paths resolve against the run working directory, and the file must be inside it.',
402
+ },
403
+ contentType: {
404
+ type: 'string',
405
+ description: 'MIME type of the bytes, e.g. image/png or video/mp4. Inferred from the file extension when omitted.',
406
+ },
407
+ filename: {
408
+ type: 'string',
409
+ description: 'Optional display name recorded in the envelope. Defaults to the file name.',
410
+ },
411
+ },
412
+ additionalProperties: false,
413
+ },
414
+ handler: async (args) => {
415
+ const gone = terminalGuard();
416
+ if (gone !== undefined)
417
+ return gone;
418
+ const file = args['file'];
419
+ if (typeof file !== 'string' || file.trim() === '') {
420
+ return textResult({ error: 'file-artifact-invalid: file must be a non-empty string' }, true);
421
+ }
422
+ const contentTypeArg = args['contentType'];
423
+ if (contentTypeArg !== undefined && (typeof contentTypeArg !== 'string' || contentTypeArg.trim() === '')) {
424
+ return textResult({ error: 'file-artifact-invalid: contentType must be a non-empty string when present' }, true);
425
+ }
426
+ const filenameArg = args['filename'];
427
+ if (filenameArg !== undefined && (typeof filenameArg !== 'string' || filenameArg.trim() === '')) {
428
+ return textResult({ error: 'file-artifact-invalid: filename must be a non-empty string when present' }, true);
429
+ }
430
+ try {
431
+ // Same two-phase containment as a submit value file, under this tool's
432
+ // own error family: the working directory is the only root a step's
433
+ // outputs may come from, and a symlink out of it is an exfiltration
434
+ // path, not a convenience.
435
+ const resolved = await resolveContainedPath(deps.workdir, file, 'file-artifact');
436
+ const bytes = new Uint8Array(await readFile(resolved));
437
+ if (bytes.byteLength === 0) {
438
+ return textResult({ error: `file-artifact-empty: ${file} is zero bytes` }, true);
439
+ }
440
+ const contentType = typeof contentTypeArg === 'string' ? contentTypeArg.trim() : guessContentType(resolved);
441
+ const filename = typeof filenameArg === 'string' ? filenameArg.trim() : basename(resolved);
442
+ const res = await hub.putFileArtifact({ workflow, bytes, contentType, filename });
443
+ // Hand back the envelope EXACTLY as it must be submitted. The hub's
444
+ // `text` is dropped from the pointer so the model cannot paste a field
445
+ // the artifact schema does not know about.
446
+ const pointer = {
447
+ __file: res.__file,
448
+ hash: res.hash,
449
+ size: res.size,
450
+ contentType: res.contentType,
451
+ ...(res.filename !== undefined ? { filename: res.filename } : {}),
452
+ };
453
+ return textResult({
454
+ pointer,
455
+ text: `Stored ${String(bytes.byteLength)} bytes as ${contentType}. Submit this pointer as your value, or embed it in one.`,
456
+ });
457
+ }
458
+ catch (e) {
459
+ return textResult({ error: errMsg(e) }, true);
460
+ }
461
+ },
462
+ };
345
463
  const registrations = {
346
464
  get_order: getOrderTool,
347
465
  submit: submitTool,
348
466
  reject: rejectTool,
349
467
  ask: askTool,
468
+ put_file_artifact: putFileArtifactTool,
350
469
  };
351
470
  const selected = deps.tools ?? HOLD_MCP_TOOL_NAMES;
352
471
  return { tools: selected.map((name) => registrations[name]), loop };
@@ -1,4 +1,4 @@
1
- import type { AnswerApprovalRequest, AnswerApprovalResponse, AskRequest, AskResponse, GetRostersResponse, ListHarnessModelsResponse, ListPendingApprovalsResponse, RequestApprovalRequest, RequestApprovalResponse, GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, RetryArtifactRequest, RetryArtifactResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
1
+ import type { AnswerApprovalRequest, AnswerApprovalResponse, AskRequest, AskResponse, GetRostersResponse, ListHarnessModelsResponse, ListPendingApprovalsResponse, RequestApprovalRequest, RequestApprovalResponse, GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, PutFileArtifactRequest, PutFileArtifactResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, RetryArtifactRequest, RetryArtifactResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
2
2
  export interface HubClientOptions {
3
3
  /** Hub origin, e.g. `https://hub.owenloop.dev` (no trailing slash needed). */
4
4
  origin: string;
@@ -59,5 +59,14 @@ export interface HubClient {
59
59
  wake(cursor?: number): Promise<WakeResponse>;
60
60
  /** B4 Shift presence register/refresh. */
61
61
  presencePing(req: PresencePingRequest): Promise<PresencePingResponse>;
62
+ /**
63
+ * Store opaque bytes as a file artifact and return the envelope naming them.
64
+ *
65
+ * The only byte-bodied call on this client. Everything else sends JSON, so
66
+ * this one bypasses `post` rather than teaching `post` a second body mode:
67
+ * one call site with an explicit content type is easier to audit than a
68
+ * shared helper that silently means two different things.
69
+ */
70
+ putFileArtifact(req: PutFileArtifactRequest): Promise<PutFileArtifactResponse>;
62
71
  }
63
72
  export declare function createHubClient(opts: HubClientOptions): HubClient;
@@ -9,6 +9,11 @@
9
9
  * for `whoami`), and parses the `{ text, ...data }` envelope. Non-2xx becomes a
10
10
  * `HubError`.
11
11
  *
12
+ * `putFileArtifact` is the single exception to the JSON rule: its body is the
13
+ * asset's raw bytes under the asset's own content type. Base64 in a JSON field
14
+ * would inflate every upload by a third and force a multi-megabyte file through
15
+ * a JavaScript string, so the bytes travel as bytes.
16
+ *
12
17
  * PRESENCE (B4) + WAKE (B5): the C1 client deliberately omitted these because
13
18
  * their hub surface did not exist yet. Both are merged now, so C3 adds
14
19
  * `presencePing` (POST `/api/presence_ping`) and `wake` (GET `/api/wake`,
@@ -76,6 +81,23 @@ export function createHubClient(opts) {
76
81
  });
77
82
  return parse(res);
78
83
  }
84
+ async function postBytes(path, req) {
85
+ const token = await opts.getToken();
86
+ const headers = {
87
+ authorization: `Bearer ${token}`,
88
+ 'content-type': req.contentType,
89
+ };
90
+ // The name rides a header rather than the body because the body IS the
91
+ // bytes. It is a display label only; the hub never resolves it as a path.
92
+ if (req.filename !== undefined)
93
+ headers['x-file-name'] = req.filename;
94
+ const res = await fetchImpl(`${base}${path}?workflow=${encodeURIComponent(req.workflow)}`, {
95
+ method: 'POST',
96
+ headers,
97
+ body: req.bytes,
98
+ });
99
+ return parse(res);
100
+ }
79
101
  return {
80
102
  whatsNext: (req) => post('whats_next', req),
81
103
  getOrder: (req) => post('get_order', req),
@@ -96,5 +118,6 @@ export function createHubClient(opts) {
96
118
  // (the hub treats missing/invalid as a `changed: true` first sweep).
97
119
  wake: (cursor) => get('wake', typeof cursor === 'number' ? `cursor=${encodeURIComponent(String(cursor))}` : undefined),
98
120
  presencePing: (req) => post('presence_ping', req),
121
+ putFileArtifact: (req) => postBytes('/api/file-artifacts', req),
99
122
  };
100
123
  }
@@ -257,6 +257,20 @@ export interface OrderPacket {
257
257
  * proof-aware hub. Absent from any hub that does not store submit proofs;
258
258
  * consume-side verification then reports the artifact as unproven. */
259
259
  consumesProof?: string;
260
+ /** Calls-boundary relay hints, keyed by the PARENT artifact path. When a
261
+ * consumed path was produced by a `calls:` step, no submission record can
262
+ * exist for the parent path: the engine folds the child's outcome into it
263
+ * without a `submit`. A relay-aware hub places the CHILD's own signed
264
+ * submission record under the parent path in `consumesProof` and names
265
+ * here the child it came from: the child definition digest the parent pins,
266
+ * the pinned child outcome version, and the child outcome stem. A worker
267
+ * corroborates every hint against its verified local definition bytes
268
+ * before trusting the record; the hints never admit a proof-less path. */
269
+ consumesProofRelay?: Record<string, {
270
+ childDefDigest: string;
271
+ childVersion: number;
272
+ childOutcome: string;
273
+ }>;
260
274
  /** The owed outputs and their reason threads. */
261
275
  owes: Array<{
262
276
  path: string;
@@ -412,6 +426,37 @@ export interface SubmitResponse extends HubResponse {
412
426
  outcome?: string;
413
427
  closed?: boolean;
414
428
  }
429
+ /**
430
+ * Upload opaque bytes and get back the small JSON envelope that names them.
431
+ *
432
+ * This is the one hub call that does NOT send JSON. The bytes go up as the raw
433
+ * request body with their own content type, because a base64 round-trip would
434
+ * inflate a large asset by a third and force the whole file through a string.
435
+ */
436
+ export interface PutFileArtifactRequest {
437
+ /** Workflow the blob belongs to — it scopes the R2 key and its retention. */
438
+ workflow: string;
439
+ bytes: Uint8Array;
440
+ /** MIME type recorded in the envelope and served back on download. */
441
+ contentType: string;
442
+ /** Optional display name; the hub records it verbatim and never trusts it as a path. */
443
+ filename?: string;
444
+ }
445
+ /**
446
+ * The envelope, which IS the artifact value. `__file` is the discriminator the
447
+ * hub's pointer walk looks for; `hash` is the content address (so re-uploading
448
+ * identical bytes is free); `size` and `contentType` describe bytes a def can
449
+ * constrain with ordinary JSON Schema even though it can never see them.
450
+ */
451
+ export interface FileArtifactPointer {
452
+ __file: true;
453
+ hash: string;
454
+ size: number;
455
+ contentType: string;
456
+ filename?: string;
457
+ }
458
+ export interface PutFileArtifactResponse extends HubResponse, FileArtifactPointer {
459
+ }
415
460
  /**
416
461
  * Invalidate an artifact through the claiming worker's consume-edge authority.
417
462
  * `by` is deliberately absent: the hub derives the actor from the claiming
@@ -31,7 +31,7 @@ function parseStartArgs(args) {
31
31
  const parsed = { crews: [] };
32
32
  const valueFlags = new Set([
33
33
  '--origin', '--as', '--name', '--cap', '--max-agents', '--exec-reserve', '--local-queue-hold', '--poll-interval',
34
- '--cache-dir', '--state-dir', '--log-dir', '--log-max-age', '--work-root',
34
+ '--cache-dir', '--state-dir', '--log-dir', '--log-max-age', '--work-root', '--disk-floor',
35
35
  ]);
36
36
  for (let i = 0; i < args.length; i++) {
37
37
  const raw = args[i];
@@ -94,6 +94,12 @@ function parseStartArgs(args) {
94
94
  return { crews: parsed.crews, error: n };
95
95
  parsed.localQueueHoldMs = n;
96
96
  }
97
+ else if (name === '--disk-floor') {
98
+ const n = intValue(value, '--disk-floor');
99
+ if (typeof n !== 'number')
100
+ return { crews: parsed.crews, error: n };
101
+ parsed.diskFloorBytes = n;
102
+ }
97
103
  else if (name === '--poll-interval') {
98
104
  const n = intValue(value, '--poll-interval');
99
105
  if (typeof n !== 'number')
@@ -17,6 +17,7 @@ import { type Roster } from '../agent/capability-model.ts';
17
17
  * and `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, above the 14-day default.
18
18
  * - `commandRouting` — who runs `executor: 'command'` steps this machine sees.
19
19
  * - `execReserve` — slots within dispatch cap reserved from agent work.
20
+ * - `diskFloorBytes` — free bytes required before starting new work.
20
21
  * - `defPolicy` — local publication trust policy (`warn` by default).
21
22
  */
22
23
  export interface Settings {
@@ -78,6 +79,16 @@ export interface Settings {
78
79
  * `--exec-reserve`; default 1.
79
80
  */
80
81
  execReserve?: number;
82
+ /**
83
+ * Free bytes the shift insists on, on the volume holding `workRoot`, before
84
+ * it will START another order. A full disk kills children mid-step with a
85
+ * bare ENOSPC, so the shift declines new work rather than feeding orders to a
86
+ * disk that cannot hold them; it keeps polling and resumes by itself when
87
+ * space returns. `0` disables the check. Fallback below `--disk-floor`;
88
+ * default 1 GiB. This is a floor for STARTING work, not a promise that any
89
+ * particular step will fit.
90
+ */
91
+ diskFloorBytes?: number;
81
92
  /**
82
93
  * How long a shift may retain an undispatchable claim locally before
83
94
  * returning it to the hub. Default 0: never retain it locally.
@@ -139,7 +150,7 @@ export interface Settings {
139
150
  roster?: Roster;
140
151
  }
141
152
  /** The known settings keys, in the order `owenloop work settings` prints them. */
142
- export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "shiftLogDir", "shiftLogMaxAgeMs", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "execReserve", "localQueueHoldMs", "workRoot", "workRepo", "allowedWorkdirRoots", "roster"];
153
+ export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "shiftLogDir", "shiftLogMaxAgeMs", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "execReserve", "diskFloorBytes", "localQueueHoldMs", "workRoot", "workRepo", "allowedWorkdirRoots", "roster"];
143
154
  /**
144
155
  * Keys owenloop still RECOGNIZES but no longer acts on. Each one produces a
145
156
  * warning naming what replaced it, and is excluded from `unrecognized` so the
@@ -29,6 +29,7 @@ export const KNOWN_SETTINGS_KEYS = [
29
29
  'artifactPolicy',
30
30
  'maxConcurrentAgents',
31
31
  'execReserve',
32
+ 'diskFloorBytes',
32
33
  'localQueueHoldMs',
33
34
  'workRoot',
34
35
  'workRepo',
@@ -104,6 +105,12 @@ export function validateSettings(raw, path) {
104
105
  throw bad('execReserve', 'a non-negative integer', v);
105
106
  }
106
107
  }
108
+ if ('diskFloorBytes' in obj) {
109
+ const v = obj['diskFloorBytes'];
110
+ if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
111
+ throw bad('diskFloorBytes', 'a non-negative integer', v);
112
+ }
113
+ }
107
114
  if ('localQueueHoldMs' in obj) {
108
115
  const v = obj['localQueueHoldMs'];
109
116
  if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Is there enough room on this disk to START another piece of work?
3
+ *
4
+ * A shift's children are the heaviest writers on the machine: a clone, a
5
+ * dependency install, a build tree, and a transcript per agent turn. When the
6
+ * volume holding the work root fills, those children do not fail politely. The
7
+ * incident this exists for is recorded in `loop.ts`'s `noteWorkerFailure`
8
+ * docstring: a worker "exited 1 with no signal, killed by ENOSPC inside its own
9
+ * error logging" — the process died while trying to say why it was dying, so
10
+ * the shift saw a bare non-zero exit and re-offered the order onto the same
11
+ * full disk, forever.
12
+ *
13
+ * WHY THIS REFUSES WORK INSTEAD OF STOPPING THE SHIFT. A full disk is a LOCAL
14
+ * fault, like the vanished `TMPDIR` that `host-preflight.ts` answers for, but
15
+ * unlike it a full disk SELF-HEALS: a large file gets deleted, a cache is
16
+ * pruned, another process finishes and releases its scratch space. Exiting the
17
+ * shift would turn a condition that commonly clears in minutes into an outage
18
+ * that needs a human to notice and restart a daemon. So this gate does the one
19
+ * thing that is both safe and reversible — it declines to take on NEW work,
20
+ * keeps polling, and starts dispatching again by itself the moment space
21
+ * returns. Work already in flight is left alone: killing a nearly-finished
22
+ * child frees little and destroys everything it had done.
23
+ *
24
+ * WHAT IT DOES NOT PROMISE. This is a floor for STARTING work, not a guarantee
25
+ * that a step will finish. Nothing here knows how much space the next order
26
+ * needs, and a step that wants 40 GiB will still die on a disk holding 2. The
27
+ * value of the gate is not that it prevents every ENOSPC; it is that when the
28
+ * disk is the reason nothing is moving, a record says so by name instead of the
29
+ * operator reading a wall of unexplained exit-1s.
30
+ *
31
+ * FAIL-OPEN, DELIBERATELY. If the free-space probe itself fails — an
32
+ * unsupported filesystem, a platform without `statfs`, a path that races away
33
+ * between the walk and the call — this reports `unknown` and the caller
34
+ * dispatches. A disk check that refused work whenever it could not measure the
35
+ * disk would convert its own blind spot into the total outage it exists to
36
+ * prevent, and it would do so on exactly the exotic hosts least likely to be
37
+ * debugged quickly. The measured failure mode is a full disk, not an
38
+ * unmeasurable one.
39
+ */
40
+ /**
41
+ * How much room the shift insists on before starting anything new.
42
+ *
43
+ * Chosen as a DISTRESS threshold rather than a sufficiency threshold. Below
44
+ * roughly a gibibyte a general-purpose developer machine cannot complete a
45
+ * dependency install or a build of any size, so nearly every order a shift
46
+ * takes will die; above it, whether an order succeeds depends on the order, and
47
+ * this module has no business guessing. The error to avoid is a floor set high
48
+ * enough to refuse work that would have succeeded, because a shift that will
49
+ * not take work is worse than a shift that occasionally loses one to ENOSPC —
50
+ * which is why the default is low and the operator can lower it further.
51
+ */
52
+ export declare const DEFAULT_DISK_FLOOR_BYTES: number;
53
+ /**
54
+ * `--disk-floor` > `settings.diskFloorBytes` > the default, matching every
55
+ * other shift tunable. `0` disables the gate: an operator who is deliberately
56
+ * running a machine close to full, or who has hit a floor this module got
57
+ * wrong, must be able to say so without downgrading the CLI.
58
+ */
59
+ export declare function resolveDiskFloorBytes(flagFloor: number | undefined, settingsFloor: number | undefined): number;
60
+ /** The one filesystem call this module makes, as an injectable seam. */
61
+ export interface StatfsProbe {
62
+ /** Bytes available to an unprivileged writer, or `undefined` if unmeasurable. */
63
+ freeBytes: (path: string) => number | undefined;
64
+ exists: (path: string) => boolean;
65
+ }
66
+ export declare const realStatfsProbe: StatfsProbe;
67
+ /**
68
+ * The nearest ancestor of `path` that exists, so free space can be measured for
69
+ * a directory the shift has not created yet.
70
+ *
71
+ * A work root is normally absent on a first run — `resolveWorkRoot` defaults it
72
+ * to `<cacheDir>/work` and `prepareWorkdir` mkdir -p's it on demand — so a
73
+ * check that required the path to exist would report `unknown` on every clean
74
+ * install and never fire when it mattered. This is the same premise that an
75
+ * earlier draft of `host-preflight.ts` got wrong; the difference is that a
76
+ * missing directory is not a fault here, merely a reason to ask its parent.
77
+ *
78
+ * Bounded by the walk reaching the filesystem root, where `dirname` becomes a
79
+ * fixed point, so a path that exists nowhere terminates rather than looping.
80
+ */
81
+ export declare function nearestExistingAncestor(path: string, fs: StatfsProbe): string | undefined;
82
+ export type DiskSpace = {
83
+ state: 'ok';
84
+ path: string;
85
+ freeBytes: number;
86
+ floorBytes: number;
87
+ } | {
88
+ state: 'low';
89
+ path: string;
90
+ freeBytes: number;
91
+ floorBytes: number;
92
+ }
93
+ /** Unmeasurable, or the gate is switched off. The caller dispatches. */
94
+ | {
95
+ state: 'unknown';
96
+ path: string;
97
+ };
98
+ /** Render a byte count the way an operator reading a log line wants it. */
99
+ export declare function formatBytes(bytes: number): string;
100
+ /**
101
+ * Measure free space for the volume that will hold the shift's work.
102
+ *
103
+ * Returns `unknown` — never `low` — when the floor is disabled or the disk
104
+ * cannot be measured, so that a caller written as `if (state === 'low')` treats
105
+ * every uncertainty as permission to proceed.
106
+ */
107
+ export declare function checkDiskFloor(workRoot: string, floorBytes: number, fs?: StatfsProbe): DiskSpace;
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Is there enough room on this disk to START another piece of work?
3
+ *
4
+ * A shift's children are the heaviest writers on the machine: a clone, a
5
+ * dependency install, a build tree, and a transcript per agent turn. When the
6
+ * volume holding the work root fills, those children do not fail politely. The
7
+ * incident this exists for is recorded in `loop.ts`'s `noteWorkerFailure`
8
+ * docstring: a worker "exited 1 with no signal, killed by ENOSPC inside its own
9
+ * error logging" — the process died while trying to say why it was dying, so
10
+ * the shift saw a bare non-zero exit and re-offered the order onto the same
11
+ * full disk, forever.
12
+ *
13
+ * WHY THIS REFUSES WORK INSTEAD OF STOPPING THE SHIFT. A full disk is a LOCAL
14
+ * fault, like the vanished `TMPDIR` that `host-preflight.ts` answers for, but
15
+ * unlike it a full disk SELF-HEALS: a large file gets deleted, a cache is
16
+ * pruned, another process finishes and releases its scratch space. Exiting the
17
+ * shift would turn a condition that commonly clears in minutes into an outage
18
+ * that needs a human to notice and restart a daemon. So this gate does the one
19
+ * thing that is both safe and reversible — it declines to take on NEW work,
20
+ * keeps polling, and starts dispatching again by itself the moment space
21
+ * returns. Work already in flight is left alone: killing a nearly-finished
22
+ * child frees little and destroys everything it had done.
23
+ *
24
+ * WHAT IT DOES NOT PROMISE. This is a floor for STARTING work, not a guarantee
25
+ * that a step will finish. Nothing here knows how much space the next order
26
+ * needs, and a step that wants 40 GiB will still die on a disk holding 2. The
27
+ * value of the gate is not that it prevents every ENOSPC; it is that when the
28
+ * disk is the reason nothing is moving, a record says so by name instead of the
29
+ * operator reading a wall of unexplained exit-1s.
30
+ *
31
+ * FAIL-OPEN, DELIBERATELY. If the free-space probe itself fails — an
32
+ * unsupported filesystem, a platform without `statfs`, a path that races away
33
+ * between the walk and the call — this reports `unknown` and the caller
34
+ * dispatches. A disk check that refused work whenever it could not measure the
35
+ * disk would convert its own blind spot into the total outage it exists to
36
+ * prevent, and it would do so on exactly the exotic hosts least likely to be
37
+ * debugged quickly. The measured failure mode is a full disk, not an
38
+ * unmeasurable one.
39
+ */
40
+ import { statfsSync } from 'node:fs';
41
+ import { dirname, resolve } from 'node:path';
42
+ /** One gibibyte, the default floor. */
43
+ const GIB = 1024 * 1024 * 1024;
44
+ /**
45
+ * How much room the shift insists on before starting anything new.
46
+ *
47
+ * Chosen as a DISTRESS threshold rather than a sufficiency threshold. Below
48
+ * roughly a gibibyte a general-purpose developer machine cannot complete a
49
+ * dependency install or a build of any size, so nearly every order a shift
50
+ * takes will die; above it, whether an order succeeds depends on the order, and
51
+ * this module has no business guessing. The error to avoid is a floor set high
52
+ * enough to refuse work that would have succeeded, because a shift that will
53
+ * not take work is worse than a shift that occasionally loses one to ENOSPC —
54
+ * which is why the default is low and the operator can lower it further.
55
+ */
56
+ export const DEFAULT_DISK_FLOOR_BYTES = GIB;
57
+ /**
58
+ * `--disk-floor` > `settings.diskFloorBytes` > the default, matching every
59
+ * other shift tunable. `0` disables the gate: an operator who is deliberately
60
+ * running a machine close to full, or who has hit a floor this module got
61
+ * wrong, must be able to say so without downgrading the CLI.
62
+ */
63
+ export function resolveDiskFloorBytes(flagFloor, settingsFloor) {
64
+ return flagFloor ?? settingsFloor ?? DEFAULT_DISK_FLOOR_BYTES;
65
+ }
66
+ export const realStatfsProbe = {
67
+ freeBytes: (path) => {
68
+ try {
69
+ const fs = statfsSync(path);
70
+ /*
71
+ * `bavail`, NOT `bfree`. `bfree` counts blocks the filesystem has reserved
72
+ * for root, which this process cannot write into — reading it would let
73
+ * the gate report several hundred megabytes of headroom that no child can
74
+ * actually use, on precisely the full disk the gate exists to catch.
75
+ */
76
+ const free = Number(fs.bavail) * Number(fs.bsize);
77
+ return Number.isFinite(free) && free >= 0 ? free : undefined;
78
+ }
79
+ catch {
80
+ return undefined;
81
+ }
82
+ },
83
+ exists: (path) => {
84
+ try {
85
+ statfsSync(path);
86
+ return true;
87
+ }
88
+ catch {
89
+ return false;
90
+ }
91
+ },
92
+ };
93
+ /**
94
+ * The nearest ancestor of `path` that exists, so free space can be measured for
95
+ * a directory the shift has not created yet.
96
+ *
97
+ * A work root is normally absent on a first run — `resolveWorkRoot` defaults it
98
+ * to `<cacheDir>/work` and `prepareWorkdir` mkdir -p's it on demand — so a
99
+ * check that required the path to exist would report `unknown` on every clean
100
+ * install and never fire when it mattered. This is the same premise that an
101
+ * earlier draft of `host-preflight.ts` got wrong; the difference is that a
102
+ * missing directory is not a fault here, merely a reason to ask its parent.
103
+ *
104
+ * Bounded by the walk reaching the filesystem root, where `dirname` becomes a
105
+ * fixed point, so a path that exists nowhere terminates rather than looping.
106
+ */
107
+ export function nearestExistingAncestor(path, fs) {
108
+ let current = resolve(path);
109
+ for (;;) {
110
+ if (fs.exists(current))
111
+ return current;
112
+ const parent = dirname(current);
113
+ if (parent === current)
114
+ return undefined;
115
+ current = parent;
116
+ }
117
+ }
118
+ /** Render a byte count the way an operator reading a log line wants it. */
119
+ export function formatBytes(bytes) {
120
+ if (bytes >= GIB)
121
+ return `${(bytes / GIB).toFixed(1)} GiB`;
122
+ if (bytes >= 1024 * 1024)
123
+ return `${Math.round(bytes / (1024 * 1024))} MiB`;
124
+ return `${bytes} B`;
125
+ }
126
+ /**
127
+ * Measure free space for the volume that will hold the shift's work.
128
+ *
129
+ * Returns `unknown` — never `low` — when the floor is disabled or the disk
130
+ * cannot be measured, so that a caller written as `if (state === 'low')` treats
131
+ * every uncertainty as permission to proceed.
132
+ */
133
+ export function checkDiskFloor(workRoot, floorBytes, fs = realStatfsProbe) {
134
+ if (floorBytes <= 0)
135
+ return { state: 'unknown', path: workRoot };
136
+ const probed = nearestExistingAncestor(workRoot, fs);
137
+ if (probed === undefined)
138
+ return { state: 'unknown', path: workRoot };
139
+ const free = fs.freeBytes(probed);
140
+ if (free === undefined)
141
+ return { state: 'unknown', path: probed };
142
+ return {
143
+ state: free < floorBytes ? 'low' : 'ok',
144
+ path: probed,
145
+ freeBytes: free,
146
+ floorBytes,
147
+ };
148
+ }