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.
- package/CHANGELOG.md +21 -0
- package/dist/packages/work/src/agent/brief.d.ts +10 -0
- package/dist/packages/work/src/agent/brief.js +38 -0
- package/dist/packages/work/src/agent/loop.js +4 -0
- package/dist/packages/work/src/consumed-verifier.d.ts +22 -2
- package/dist/packages/work/src/consumed-verifier.js +131 -12
- package/dist/packages/work/src/contained-path.d.ts +18 -0
- package/dist/packages/work/src/contained-path.js +42 -0
- package/dist/packages/work/src/exec/instructions.js +43 -3
- package/dist/packages/work/src/harness/claude.js +21 -0
- package/dist/packages/work/src/harness/codex.js +29 -0
- package/dist/packages/work/src/harness/contract.d.ts +26 -0
- package/dist/packages/work/src/hold/mcp.d.ts +3 -40
- package/dist/packages/work/src/hold/mcp.js +121 -2
- package/dist/packages/work/src/hub/client.d.ts +10 -1
- package/dist/packages/work/src/hub/client.js +23 -0
- package/dist/packages/work/src/hub/types.d.ts +45 -0
- package/dist/packages/work/src/roles/shift.js +7 -1
- package/dist/packages/work/src/settings/settings.d.ts +12 -1
- package/dist/packages/work/src/settings/settings.js +7 -0
- package/dist/packages/work/src/shift/disk-floor.d.ts +107 -0
- package/dist/packages/work/src/shift/disk-floor.js +148 -0
- package/dist/packages/work/src/shift/host-preflight.d.ts +85 -0
- package/dist/packages/work/src/shift/host-preflight.js +112 -0
- package/dist/packages/work/src/shift/loop.d.ts +18 -0
- package/dist/packages/work/src/shift/loop.js +179 -7
- package/dist/packages/work/src/shift/protocol.d.ts +62 -1
- package/dist/packages/work/src/shift/runtime.d.ts +2 -0
- package/dist/packages/work/src/shift/runtime.js +17 -0
- package/dist/packages/work/src/submit-file.d.ts +3 -2
- package/dist/packages/work/src/submit-file.js +6 -22
- package/dist/src/crypto/records.d.ts +1 -0
- package/dist/src/crypto/records.js +1 -0
- package/dist/src/crypto/verify-consumed.d.ts +16 -1
- package/dist/src/crypto/verify-consumed.js +21 -6
- package/dist/src/schemas/index.d.ts +23 -0
- package/dist/src/schemas/order.v1.schema.json +14 -0
- package/dist/src/store/index.d.ts +1 -1
- package/dist/src/store/instruction-source.d.ts +15 -0
- package/dist/src/store/instruction-source.js +64 -4
- package/dist/src/store/types.d.ts +6 -2
- package/dist/src/store/types.js +5 -1
- package/dist/src/types.d.ts +11 -0
- package/docs/bundles.md +5 -1
- package/docs/cli.md +8 -5
- package/docs/crypto.md +46 -0
- package/docs/shift-logs.md +64 -7
- package/docs/wire-contracts.md +15 -2
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- 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
|
|
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
|
+
}
|