owenloop 0.5.1 → 0.5.3
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 +30 -0
- package/README.md +9 -2
- package/dist/packages/work/src/agent/brief.d.ts +21 -0
- package/dist/packages/work/src/agent/brief.js +42 -1
- package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
- package/dist/packages/work/src/agent/capability-model.js +148 -0
- package/dist/packages/work/src/agent/loop.d.ts +47 -4
- package/dist/packages/work/src/agent/loop.js +83 -53
- package/dist/packages/work/src/exec/loop.d.ts +17 -0
- package/dist/packages/work/src/exec/loop.js +195 -34
- package/dist/packages/work/src/exec/runner.js +15 -5
- package/dist/packages/work/src/harness/claude.js +69 -9
- package/dist/packages/work/src/harness/codex.js +56 -8
- package/dist/packages/work/src/harness/contract.d.ts +65 -1
- package/dist/packages/work/src/harness/contract.js +56 -0
- package/dist/packages/work/src/harness/session-store.d.ts +3 -1
- package/dist/packages/work/src/harness/session-store.js +46 -22
- package/dist/packages/work/src/hold/mcp.js +9 -2
- package/dist/packages/work/src/hub/client.d.ts +7 -1
- package/dist/packages/work/src/hub/client.js +1 -0
- package/dist/packages/work/src/hub/types.d.ts +71 -3
- package/dist/packages/work/src/roles/agent-run.js +8 -9
- package/dist/packages/work/src/roles/hold.d.ts +2 -0
- package/dist/packages/work/src/roles/hold.js +39 -8
- package/dist/packages/work/src/roles/settings.js +18 -6
- package/dist/packages/work/src/roles/shift.js +13 -1
- package/dist/packages/work/src/settings/settings.d.ts +60 -7
- package/dist/packages/work/src/settings/settings.js +69 -22
- package/dist/packages/work/src/shift/logretention.d.ts +253 -0
- package/dist/packages/work/src/shift/logretention.js +407 -0
- package/dist/packages/work/src/shift/logsink.d.ts +14 -0
- package/dist/packages/work/src/shift/logsink.js +98 -0
- package/dist/packages/work/src/shift/loop.d.ts +18 -1
- package/dist/packages/work/src/shift/loop.js +250 -12
- package/dist/packages/work/src/shift/protocol.d.ts +124 -1
- package/dist/packages/work/src/shift/protocol.js +14 -0
- package/dist/packages/work/src/shift/runtime.d.ts +14 -0
- package/dist/packages/work/src/shift/runtime.js +229 -6
- package/dist/packages/work/src/shift/server.d.ts +13 -0
- package/dist/packages/work/src/shift/server.js +61 -36
- package/dist/packages/work/src/shift/spawn.d.ts +78 -5
- package/dist/packages/work/src/shift/spawn.js +158 -12
- package/dist/packages/work/src/shift/state.d.ts +25 -0
- package/dist/packages/work/src/shift/state.js +29 -5
- package/dist/packages/work/src/shift/truncate.d.ts +35 -0
- package/dist/packages/work/src/shift/truncate.js +73 -0
- package/dist/packages/work/src/submit-proof.d.ts +31 -6
- package/dist/packages/work/src/submit-proof.js +33 -7
- package/dist/packages/work/src/submit-value.d.ts +48 -0
- package/dist/packages/work/src/submit-value.js +118 -0
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +11 -0
- package/dist/src/bundle/runtime.d.ts +1 -1
- package/dist/src/bundle/runtime.js +9 -0
- package/dist/src/capabilities.d.ts +93 -0
- package/dist/src/capabilities.js +101 -0
- package/dist/src/cli.js +37 -11
- package/dist/src/crypto/records.d.ts +3 -0
- package/dist/src/crypto/records.js +11 -0
- package/dist/src/defs.js +192 -4
- package/dist/src/engine.d.ts +112 -3
- package/dist/src/engine.js +224 -28
- package/dist/src/hub.d.ts +27 -11
- package/dist/src/hub.js +24 -18
- package/dist/src/index.d.ts +3 -1
- package/dist/src/index.js +4 -1
- package/dist/src/mcp/serve.js +11 -4
- package/dist/src/model.d.ts +36 -0
- package/dist/src/model.js +46 -0
- package/dist/src/schemas/index.d.ts +17 -0
- package/dist/src/schemas/order.v1.schema.json +17 -3
- package/dist/src/store.d.ts +33 -1
- package/dist/src/store.js +57 -4
- package/dist/src/types.d.ts +102 -2
- package/docs/agent-runner.md +26 -1
- package/docs/authoring.md +7 -0
- package/docs/bundles.md +103 -3
- package/docs/cli.md +127 -9
- package/docs/crypto.md +23 -7
- package/docs/shift-logs.md +642 -0
- package/docs/wire-contracts.md +34 -19
- 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
- package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
- package/dist/packages/work/src/agent/model-policy.js +0 -138
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Every order the shift dispatches becomes a DETACHED
|
|
5
5
|
* `owenloop work exec <workflow>/<run> --origin <url>` child: `detached: true`,
|
|
6
|
-
*
|
|
6
|
+
* stdin ignored, stdout and stderr appended to `<log-dir>/<run>.log` when the
|
|
7
|
+
* shift resolved a log directory (and ignored when it did not), `unref()` — so
|
|
8
|
+
* the child is its own process-group leader and
|
|
7
9
|
* survives the parent's death (SP5-verified kernel reparenting). The shift meters
|
|
8
10
|
* and hands off; the child self-leases (C5). Both ids ride the argv as the
|
|
9
11
|
* composite `<workflow>/<run>` order-id `owenloop work exec` parses, and `--origin`
|
|
@@ -18,8 +20,91 @@
|
|
|
18
20
|
* focused lifecycle regression uses harmless local children.
|
|
19
21
|
*/
|
|
20
22
|
import { spawn } from 'node:child_process';
|
|
23
|
+
import { closeSync, openSync } from 'node:fs';
|
|
21
24
|
import { resolveOwenloopBin } from "../owenloop-bin.js";
|
|
25
|
+
import { runLogFile } from "./logretention.js";
|
|
22
26
|
export { resolveOwenloopBin } from "../owenloop-bin.js";
|
|
27
|
+
/**
|
|
28
|
+
* Open one worker's log for appending, or give up and return `undefined`.
|
|
29
|
+
*
|
|
30
|
+
* A LOG THAT WILL NOT OPEN MUST NEVER FAIL AN ORDER. A full disk, a read-only
|
|
31
|
+
* directory, or a path an operator deleted underneath the shift costs
|
|
32
|
+
* observability for that worker and nothing else: the caller falls back to
|
|
33
|
+
* `'ignore'` on slots 1 and 2 and dispatches anyway.
|
|
34
|
+
*
|
|
35
|
+
* `report` is the caller's LATCHED sink — see `createDefaultSpawner`. This
|
|
36
|
+
* function reports on every failure it sees; the latch that turns that into one
|
|
37
|
+
* line per shift lives with the spawner, which is the thing whose lifetime the
|
|
38
|
+
* latch is scoped to.
|
|
39
|
+
*
|
|
40
|
+
* MODE 0600, OWNER ONLY. A worker runs authored workflow content, so its
|
|
41
|
+
* stdout and stderr are attacker-influenceable data and may contain whatever a
|
|
42
|
+
* step printed — including a token a step echoed. `exec/loop.ts` already writes
|
|
43
|
+
* its agent-produced artifact JSON with `mode: 0o600` for exactly this reason;
|
|
44
|
+
* a raw worker log is the same data class and strictly less filtered. Without
|
|
45
|
+
* an explicit mode `openSync` creates 0666 & ~umask, which is 0644 under the
|
|
46
|
+
* usual 022 — readable by every local account.
|
|
47
|
+
*
|
|
48
|
+
* THE MODE APPLIES ONLY WHEN THE FILE IS CREATED. Append mode never re-chmods,
|
|
49
|
+
* so a `<run>.log` left behind by a build from before this became explicit
|
|
50
|
+
* keeps its old permissions. That is deliberate: silently tightening a file an
|
|
51
|
+
* operator may have already handed to an uploader account is a worse surprise
|
|
52
|
+
* than a stale-permission file the operator can fix with one `chmod`.
|
|
53
|
+
*/
|
|
54
|
+
function openWorkerLog(path, report) {
|
|
55
|
+
try {
|
|
56
|
+
return openSync(path, 'a', 0o600);
|
|
57
|
+
}
|
|
58
|
+
catch (e) {
|
|
59
|
+
report(`owenloop shift: could not open worker log ${path}: ${err(e)} — dispatching with its output discarded`);
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
function err(e) {
|
|
64
|
+
return e instanceof Error ? e.message : String(e);
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* The harness id to REPORT on an agent-run worker failure — a best-effort
|
|
68
|
+
* mirror of the id the CHILD resolved, never an independent decision.
|
|
69
|
+
*
|
|
70
|
+
* It mirrors `resolveAdapter` in `roles/agent-run.ts`, minus the `--harness`
|
|
71
|
+
* rank the Shift never emits:
|
|
72
|
+
*
|
|
73
|
+
* 1. `OWENLOOP_HARNESS` when the variable is SET. Set-but-blank is not a
|
|
74
|
+
* fall-through: the child refuses that config outright and names it
|
|
75
|
+
* `<empty OWENLOOP_HARNESS>`, so the failure event says the same thing.
|
|
76
|
+
* 2. `spec.harness` — the prepared-cache step's `harness` field — when it is
|
|
77
|
+
* a non-empty string. An empty string counts as absent, matching the
|
|
78
|
+
* child.
|
|
79
|
+
* 3. Otherwise the child took the first REGISTERED adapter. This process
|
|
80
|
+
* cannot name it: the Shift is a neutral dispatcher and never imports the
|
|
81
|
+
* adapter composition root, so its own registry is empty and asking it
|
|
82
|
+
* would answer `undefined`. Report the placeholder instead.
|
|
83
|
+
*
|
|
84
|
+
* WHY THE ORDER MATTERS. It used to read `spec.harness ?? OWENLOOP_HARNESS`,
|
|
85
|
+
* which is the child's precedence INVERTED. An operator who pinned
|
|
86
|
+
* `OWENLOOP_HARNESS` on a shift whose cached step also named a harness got a
|
|
87
|
+
* failure event naming the harness that did NOT run — the single most
|
|
88
|
+
* misleading field in the record, since the harness is the first thing an
|
|
89
|
+
* operator reaches for when a worker dies.
|
|
90
|
+
*
|
|
91
|
+
* BEST-EFFORT IS DELIBERATE at rank 2. A modern agent order carries no
|
|
92
|
+
* `spec.harness` at all (the child reads the verified, order-pinned step), so
|
|
93
|
+
* rank 2 only ever fires on the legacy cache path. The alternative — the Shift
|
|
94
|
+
* verifying the order digest itself purely to label a failure — would duplicate
|
|
95
|
+
* the child's whole resolution for a diagnostic string.
|
|
96
|
+
*
|
|
97
|
+
* `env` is the environment the CHILD is spawned with (`plan.options.env`), not
|
|
98
|
+
* this process's — they differ, and the child's is the one that decided.
|
|
99
|
+
*/
|
|
100
|
+
export function reportedHarnessId(spec, env) {
|
|
101
|
+
const fromEnv = env['OWENLOOP_HARNESS'];
|
|
102
|
+
if (fromEnv !== undefined)
|
|
103
|
+
return fromEnv.trim() === '' ? '<empty OWENLOOP_HARNESS>' : fromEnv;
|
|
104
|
+
if (spec.harness !== undefined && spec.harness !== '')
|
|
105
|
+
return spec.harness;
|
|
106
|
+
return '<registered default>';
|
|
107
|
+
}
|
|
23
108
|
/**
|
|
24
109
|
* Build the argv + options for a detached
|
|
25
110
|
* `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
|
|
@@ -48,8 +133,14 @@ export { resolveOwenloopBin } from "../owenloop-bin.js";
|
|
|
48
133
|
* inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
|
|
49
134
|
* step, registered default). The Shift command has no operator-facing harness
|
|
50
135
|
* flag, so there is no legitimate CLI override for this seam to carry.
|
|
136
|
+
*
|
|
137
|
+
* `logDir` (trailing, after `shiftId`, for the same reason) adds the worker's
|
|
138
|
+
* log DESTINATION to the plan as `<logDir>/<run>.log`. The plan still carries
|
|
139
|
+
* `stdio: ['ignore','ignore','ignore']`: opening the file is I/O, this function
|
|
140
|
+
* is pure, and `createDefaultSpawner` substitutes the descriptors. Omitted ⇒ no
|
|
141
|
+
* `logFile` key at all, and the plan is byte-identical to the pre-logging shape.
|
|
51
142
|
*/
|
|
52
|
-
export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId) {
|
|
143
|
+
export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId, logDir) {
|
|
53
144
|
const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
|
|
54
145
|
return {
|
|
55
146
|
command: execPath,
|
|
@@ -71,6 +162,7 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
|
|
|
71
162
|
...(spec.startGate !== undefined ? { OWENLOOP_START_GATE: spec.startGate } : {}),
|
|
72
163
|
},
|
|
73
164
|
},
|
|
165
|
+
...(logDir !== undefined && logDir !== '' ? { logFile: runLogFile(logDir, spec.run) } : {}),
|
|
74
166
|
};
|
|
75
167
|
}
|
|
76
168
|
/**
|
|
@@ -81,22 +173,76 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
|
|
|
81
173
|
* relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
|
|
82
174
|
* — can be supplied positionally.
|
|
83
175
|
*/
|
|
84
|
-
export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure) {
|
|
176
|
+
export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure, logging) {
|
|
177
|
+
// ONE report per shift, not one per dispatch. Every condition that stops a
|
|
178
|
+
// worker log from opening — a full disk, a read-only log directory, an
|
|
179
|
+
// operator deleting it underneath a running shift — PERSISTS across the
|
|
180
|
+
// dispatches that follow, so an unlatched report writes one stderr line per
|
|
181
|
+
// dispatch for as long as the shift runs. The event sink latches its own
|
|
182
|
+
// failure report the same way (`logsink.ts`); these are the two failure paths
|
|
183
|
+
// of the same feature and they make the operator the same promise.
|
|
184
|
+
let reportedOpenFailure = false;
|
|
185
|
+
const reportOpenFailure = (line) => {
|
|
186
|
+
if (reportedOpenFailure)
|
|
187
|
+
return;
|
|
188
|
+
reportedOpenFailure = true;
|
|
189
|
+
logging?.err?.(line);
|
|
190
|
+
};
|
|
85
191
|
return (spec) => {
|
|
86
|
-
const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId);
|
|
87
|
-
|
|
192
|
+
const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId, logging?.dir);
|
|
193
|
+
// Open the log ONCE and hand the SAME descriptor to slots 1 and 2. Opening
|
|
194
|
+
// it twice would create two independent file offsets, and the two streams
|
|
195
|
+
// would overwrite each other's bytes — silent corruption no unit test on the
|
|
196
|
+
// plan can catch. One descriptor used twice is exactly shell `2>&1`.
|
|
197
|
+
//
|
|
198
|
+
// ALWAYS APPEND, never truncate. A retried or re-armed run reuses its run
|
|
199
|
+
// id, and the prior attempt's output is precisely the evidence this feature
|
|
200
|
+
// exists to keep.
|
|
201
|
+
const logFd = plan.logFile === undefined
|
|
202
|
+
? undefined
|
|
203
|
+
: openWorkerLog(plan.logFile, reportOpenFailure);
|
|
204
|
+
const options = logFd === undefined
|
|
205
|
+
? plan.options
|
|
206
|
+
: { ...plan.options, stdio: ['ignore', logFd, logFd] };
|
|
207
|
+
let child;
|
|
208
|
+
try {
|
|
209
|
+
child = spawn(plan.command, plan.args, options);
|
|
210
|
+
}
|
|
211
|
+
finally {
|
|
212
|
+
// The parent's copy must go once the child has inherited its own dup, and
|
|
213
|
+
// it must go even when `spawn` throws. A long-lived shift that leaked one
|
|
214
|
+
// descriptor per dispatch would eventually hit EMFILE and stop
|
|
215
|
+
// dispatching entirely.
|
|
216
|
+
if (logFd !== undefined) {
|
|
217
|
+
try {
|
|
218
|
+
closeSync(logFd);
|
|
219
|
+
}
|
|
220
|
+
catch {
|
|
221
|
+
// Nothing useful remains to do with a descriptor that will not close.
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
88
225
|
const kind = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
|
|
89
|
-
const harness = kind === 'agent-run'
|
|
90
|
-
? (spec.harness ?? process.env['OWENLOOP_HARNESS'] ?? 'auto')
|
|
91
|
-
: undefined;
|
|
226
|
+
const harness = kind === 'agent-run' ? reportedHarnessId(spec, plan.options.env) : undefined;
|
|
92
227
|
// This process is the executable Shift actually launched. The harness may
|
|
93
228
|
// start its own vendor process later, but reporting or guessing that
|
|
94
229
|
// executable here would couple the neutral dispatcher to one adapter.
|
|
95
230
|
const executable = `${process.execPath} ${binPath}`;
|
|
96
|
-
//
|
|
97
|
-
// worker may keep writing diagnostics
|
|
98
|
-
// reader
|
|
99
|
-
//
|
|
231
|
+
// THE INVARIANT: no worker stdio slot is ever a PARENT-OWNED PIPE. Once
|
|
232
|
+
// Shift exits, a detached worker may keep writing diagnostics, and a pipe
|
|
233
|
+
// whose reader has vanished kills the writer with EPIPE — losing the worker,
|
|
234
|
+
// not just its output.
|
|
235
|
+
//
|
|
236
|
+
// A FILE DESCRIPTOR IS NOT A PIPE, and slots 1 and 2 are now an appended
|
|
237
|
+
// file: it outlives the parent, needs no live reader, and cannot raise
|
|
238
|
+
// EPIPE. So the invariant holds unchanged while the bytes are kept.
|
|
239
|
+
//
|
|
240
|
+
// "Agent-run stderr is untrusted" also still holds, and still means what it
|
|
241
|
+
// always meant: worker output is never quoted back as a failure message.
|
|
242
|
+
// The bounded generic lifecycle message below is what a failure reports.
|
|
243
|
+
// Untrusted is a reason not to REPEAT those bytes, never a reason to
|
|
244
|
+
// discard them before an operator can read them — reading them is the whole
|
|
245
|
+
// point of `<run>.log`.
|
|
100
246
|
let failureReported = false;
|
|
101
247
|
const report = (exitStatus, signal, message) => {
|
|
102
248
|
if (failureReported || onFailure === undefined)
|
|
@@ -32,7 +32,32 @@ export interface ReservedChild {
|
|
|
32
32
|
reservation: ChildReservation;
|
|
33
33
|
gatePath: string;
|
|
34
34
|
}
|
|
35
|
+
/**
|
|
36
|
+
* Where this shift's `<run>.json` in-flight records live.
|
|
37
|
+
*
|
|
38
|
+
* ALWAYS ABSOLUTE. `--state-dir ./state` is a legal thing for an operator to
|
|
39
|
+
* type, and while only this process joined paths onto it the relative spelling
|
|
40
|
+
* was harmless. It stopped being harmless when the log-owner registry
|
|
41
|
+
* (`logretention.ts`) began WRITING this string into a file that a DIFFERENT
|
|
42
|
+
* shift process, with a DIFFERENT working directory, reads back and probes for
|
|
43
|
+
* `<run>.json`: `./state` resolved against the wrong cwd finds no record, the
|
|
44
|
+
* in-flight gate concludes the run finished, and a live worker's log is
|
|
45
|
+
* unlinked out from under it. `resolve()` here is what makes the writer, the
|
|
46
|
+
* reader and the probe agree on ONE spelling, and it is also what keeps
|
|
47
|
+
* `ownerClaimName`'s hash stable so one shift writes one claim file rather than
|
|
48
|
+
* one per cwd it was ever started from.
|
|
49
|
+
*/
|
|
35
50
|
export declare function resolveStateDir(env: Record<string, string | undefined>, override?: string): string;
|
|
51
|
+
/**
|
|
52
|
+
* The run id as it appears in a filename, with every character a path could
|
|
53
|
+
* misread replaced.
|
|
54
|
+
*
|
|
55
|
+
* EXPORTED because the worker log `<run>.log` correlates to the in-flight
|
|
56
|
+
* record `<run>.json` BY BASENAME. Two sanitizers would be two basenames, and
|
|
57
|
+
* the correlation an operator and a future uploader both rely on would silently
|
|
58
|
+
* stop holding for any run id containing an unusual character.
|
|
59
|
+
*/
|
|
60
|
+
export declare function safeRun(run: string): string;
|
|
36
61
|
/** Persist a child record atomically. State persistence is correctness-sensitive and throws on failure. */
|
|
37
62
|
export declare function writeChildRecord(stateDir: string, record: ChildRecord): void;
|
|
38
63
|
/** Create the durable capacity reservation and closed start gate before spawn. */
|
|
@@ -11,20 +11,44 @@
|
|
|
11
11
|
*/
|
|
12
12
|
import { closeSync, existsSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
|
|
13
13
|
import { randomBytes } from 'node:crypto';
|
|
14
|
-
import { basename, join } from 'node:path';
|
|
14
|
+
import { basename, join, resolve } from 'node:path';
|
|
15
15
|
export const DEFAULT_RESERVATION_MAX_AGE_MS = 2 * 60_000;
|
|
16
|
+
/**
|
|
17
|
+
* Where this shift's `<run>.json` in-flight records live.
|
|
18
|
+
*
|
|
19
|
+
* ALWAYS ABSOLUTE. `--state-dir ./state` is a legal thing for an operator to
|
|
20
|
+
* type, and while only this process joined paths onto it the relative spelling
|
|
21
|
+
* was harmless. It stopped being harmless when the log-owner registry
|
|
22
|
+
* (`logretention.ts`) began WRITING this string into a file that a DIFFERENT
|
|
23
|
+
* shift process, with a DIFFERENT working directory, reads back and probes for
|
|
24
|
+
* `<run>.json`: `./state` resolved against the wrong cwd finds no record, the
|
|
25
|
+
* in-flight gate concludes the run finished, and a live worker's log is
|
|
26
|
+
* unlinked out from under it. `resolve()` here is what makes the writer, the
|
|
27
|
+
* reader and the probe agree on ONE spelling, and it is also what keeps
|
|
28
|
+
* `ownerClaimName`'s hash stable so one shift writes one claim file rather than
|
|
29
|
+
* one per cwd it was ever started from.
|
|
30
|
+
*/
|
|
16
31
|
export function resolveStateDir(env, override) {
|
|
17
32
|
if (override !== undefined && override.trim() !== '')
|
|
18
|
-
return override;
|
|
33
|
+
return resolve(override);
|
|
19
34
|
const xdg = env['XDG_STATE_HOME'];
|
|
20
35
|
if (xdg !== undefined && xdg.trim() !== '')
|
|
21
|
-
return
|
|
36
|
+
return resolve(xdg, 'owenloop', 'exec');
|
|
22
37
|
const home = env['HOME'];
|
|
23
38
|
if (home !== undefined && home.trim() !== '')
|
|
24
|
-
return
|
|
39
|
+
return resolve(home, '.local', 'state', 'owenloop', 'exec');
|
|
25
40
|
throw new Error('cannot locate a state directory: set OWENLOOP_STATE_DIR, XDG_STATE_HOME, or HOME');
|
|
26
41
|
}
|
|
27
|
-
|
|
42
|
+
/**
|
|
43
|
+
* The run id as it appears in a filename, with every character a path could
|
|
44
|
+
* misread replaced.
|
|
45
|
+
*
|
|
46
|
+
* EXPORTED because the worker log `<run>.log` correlates to the in-flight
|
|
47
|
+
* record `<run>.json` BY BASENAME. Two sanitizers would be two basenames, and
|
|
48
|
+
* the correlation an operator and a future uploader both rely on would silently
|
|
49
|
+
* stop holding for any run id containing an unusual character.
|
|
50
|
+
*/
|
|
51
|
+
export function safeRun(run) {
|
|
28
52
|
return run.replace(/[^A-Za-z0-9_.-]/g, '_');
|
|
29
53
|
}
|
|
30
54
|
function recordFile(stateDir, run) {
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Byte-bounding one `ShiftEvent`, shared by the two consumers that must bound it.
|
|
3
|
+
*
|
|
4
|
+
* There is exactly ONE line-size rule, and both consumers apply it:
|
|
5
|
+
* - the socket daemon (`server.ts`) measures a whole response envelope, and
|
|
6
|
+
* - the on-disk JSON Lines sink (`logsink.ts`) measures one serialized line,
|
|
7
|
+
*
|
|
8
|
+
* so the ceiling in the file matches the ceiling on the wire and a future
|
|
9
|
+
* uploader tailing the file never faces a line the socket would have refused.
|
|
10
|
+
* The two differ only in HOW bytes are counted, which is why `measure` is a
|
|
11
|
+
* parameter rather than a second copy of the algorithm.
|
|
12
|
+
*
|
|
13
|
+
* THE ENVELOPE IS NEVER TRUNCATED AWAY. `type`, `ts`, and `shiftId` are exempt:
|
|
14
|
+
* they are the fields that make a record self-describing, they are bounded by
|
|
15
|
+
* construction (a literal, an ISO-8601 timestamp, `shf_<uuid>`), and blanking
|
|
16
|
+
* them would leave a reader with a marked husk it cannot place in time or
|
|
17
|
+
* attribute to a process. `shift` — the operator-chosen name — is NOT exempt;
|
|
18
|
+
* it is unbounded input and is shortened like any other string field, and only
|
|
19
|
+
* when it is the largest one left.
|
|
20
|
+
*/
|
|
21
|
+
import { type ShiftEvent } from './protocol.ts';
|
|
22
|
+
/** Shorten `value` to at most `maxBytes` UTF-8 bytes, marker included. */
|
|
23
|
+
export declare function truncateUtf8(value: string, maxBytes: number): string;
|
|
24
|
+
/**
|
|
25
|
+
* Render one event within `maxBytes`, as `measure` counts them.
|
|
26
|
+
*
|
|
27
|
+
* A single event can be larger than the ceiling. It is delivered once with its
|
|
28
|
+
* string fields progressively halved — largest first — and an explicit
|
|
29
|
+
* `RESPONSE_TRUNCATION_MARKER`, rather than blocking every later event forever.
|
|
30
|
+
*
|
|
31
|
+
* `measure` receives the CANDIDATE event and returns the byte length the caller
|
|
32
|
+
* cares about: the socket adds its response envelope, the file sink adds the
|
|
33
|
+
* trailing newline.
|
|
34
|
+
*/
|
|
35
|
+
export declare function truncateEventToBytes(event: ShiftEvent, maxBytes: number, measure: (candidate: ShiftEvent) => number): ShiftEvent;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Byte-bounding one `ShiftEvent`, shared by the two consumers that must bound it.
|
|
3
|
+
*
|
|
4
|
+
* There is exactly ONE line-size rule, and both consumers apply it:
|
|
5
|
+
* - the socket daemon (`server.ts`) measures a whole response envelope, and
|
|
6
|
+
* - the on-disk JSON Lines sink (`logsink.ts`) measures one serialized line,
|
|
7
|
+
*
|
|
8
|
+
* so the ceiling in the file matches the ceiling on the wire and a future
|
|
9
|
+
* uploader tailing the file never faces a line the socket would have refused.
|
|
10
|
+
* The two differ only in HOW bytes are counted, which is why `measure` is a
|
|
11
|
+
* parameter rather than a second copy of the algorithm.
|
|
12
|
+
*
|
|
13
|
+
* THE ENVELOPE IS NEVER TRUNCATED AWAY. `type`, `ts`, and `shiftId` are exempt:
|
|
14
|
+
* they are the fields that make a record self-describing, they are bounded by
|
|
15
|
+
* construction (a literal, an ISO-8601 timestamp, `shf_<uuid>`), and blanking
|
|
16
|
+
* them would leave a reader with a marked husk it cannot place in time or
|
|
17
|
+
* attribute to a process. `shift` — the operator-chosen name — is NOT exempt;
|
|
18
|
+
* it is unbounded input and is shortened like any other string field, and only
|
|
19
|
+
* when it is the largest one left.
|
|
20
|
+
*/
|
|
21
|
+
import { RESPONSE_TRUNCATION_MARKER } from "./protocol.js";
|
|
22
|
+
/** Fields whose value must survive truncation intact. See the module comment. */
|
|
23
|
+
const PROTECTED_KEYS = new Set(['type', 'ts', 'shiftId']);
|
|
24
|
+
/** Shorten `value` to at most `maxBytes` UTF-8 bytes, marker included. */
|
|
25
|
+
export function truncateUtf8(value, maxBytes) {
|
|
26
|
+
if (Buffer.byteLength(value, 'utf8') <= maxBytes)
|
|
27
|
+
return value;
|
|
28
|
+
const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
|
|
29
|
+
if (maxBytes <= markerBytes)
|
|
30
|
+
return RESPONSE_TRUNCATION_MARKER;
|
|
31
|
+
let prefix = Buffer.from(value, 'utf8').subarray(0, maxBytes - markerBytes).toString('utf8');
|
|
32
|
+
while (Buffer.byteLength(prefix, 'utf8') > maxBytes - markerBytes)
|
|
33
|
+
prefix = prefix.slice(0, -1);
|
|
34
|
+
return `${prefix}${RESPONSE_TRUNCATION_MARKER}`;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Render one event within `maxBytes`, as `measure` counts them.
|
|
38
|
+
*
|
|
39
|
+
* A single event can be larger than the ceiling. It is delivered once with its
|
|
40
|
+
* string fields progressively halved — largest first — and an explicit
|
|
41
|
+
* `RESPONSE_TRUNCATION_MARKER`, rather than blocking every later event forever.
|
|
42
|
+
*
|
|
43
|
+
* `measure` receives the CANDIDATE event and returns the byte length the caller
|
|
44
|
+
* cares about: the socket adds its response envelope, the file sink adds the
|
|
45
|
+
* trailing newline.
|
|
46
|
+
*/
|
|
47
|
+
export function truncateEventToBytes(event, maxBytes, measure) {
|
|
48
|
+
const candidate = { ...event };
|
|
49
|
+
const stringKeys = Object.keys(candidate).filter((key) => typeof candidate[key] === 'string' && !PROTECTED_KEYS.has(key));
|
|
50
|
+
const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
|
|
51
|
+
while (measure(candidate) > maxBytes) {
|
|
52
|
+
const key = stringKeys
|
|
53
|
+
.filter((name) => candidate[name] !== RESPONSE_TRUNCATION_MARKER)
|
|
54
|
+
.sort((left, right) => Buffer.byteLength(String(candidate[right]), 'utf8') -
|
|
55
|
+
Buffer.byteLength(String(candidate[left]), 'utf8'))[0];
|
|
56
|
+
if (key === undefined)
|
|
57
|
+
break;
|
|
58
|
+
const value = String(candidate[key]);
|
|
59
|
+
const currentBytes = Buffer.byteLength(value, 'utf8');
|
|
60
|
+
const targetBytes = Math.max(markerBytes, Math.floor(currentBytes / 2));
|
|
61
|
+
const shortened = truncateUtf8(value, targetBytes);
|
|
62
|
+
candidate[key] = shortened === value ? RESPONSE_TRUNCATION_MARKER : shortened;
|
|
63
|
+
}
|
|
64
|
+
// Final backstop if a future event shape needs more reduction than the
|
|
65
|
+
// progressive shortening above provided. Non-string fields (and the protected
|
|
66
|
+
// envelope) are left alone, so a pathological case can still exceed the
|
|
67
|
+
// ceiling rather than lose the identity that makes the record readable.
|
|
68
|
+
if (measure(candidate) > maxBytes) {
|
|
69
|
+
for (const key of stringKeys)
|
|
70
|
+
candidate[key] = RESPONSE_TRUNCATION_MARKER;
|
|
71
|
+
}
|
|
72
|
+
return candidate;
|
|
73
|
+
}
|
|
@@ -24,12 +24,37 @@ export interface SubmitProofOptions {
|
|
|
24
24
|
export declare function buildSubmitProof(opts: SubmitProofOptions): Promise<string | undefined>;
|
|
25
25
|
/**
|
|
26
26
|
* Resolve the version named by the next submission from authoritative lifecycle
|
|
27
|
-
* metadata only
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
27
|
+
* metadata only — never from a process-local guess.
|
|
28
|
+
*
|
|
29
|
+
* Three sources, in precedence order:
|
|
30
|
+
*
|
|
31
|
+
* 1. `explicit` — a caller-supplied target, used verbatim.
|
|
32
|
+
* 2. A judge approval attests the already-submitted version captured in the
|
|
33
|
+
* claim fingerprint and does not increment it (the engine's judge-approve
|
|
34
|
+
* branch flips acceptance without bumping `version`).
|
|
35
|
+
* 3. A producer submit uses `owes[].version`, the target the hub issued for
|
|
36
|
+
* this owed output inside the claim transaction. It is the version the
|
|
37
|
+
* next successful commit lands, which is exactly what the consumer checks
|
|
38
|
+
* the proof against.
|
|
39
|
+
*
|
|
40
|
+
* Retry-safety comes from the hub, not from this function. The target is
|
|
41
|
+
* computed once inside the claim transaction and persisted with the immutable
|
|
42
|
+
* order, so every retry of the same claim — a reconnect, a lost response, a
|
|
43
|
+
* restarted holder — reads the same number. The engine's refusal paths that
|
|
44
|
+
* leave the run open (schema-reject) do not bump the artifact, so the target
|
|
45
|
+
* survives in-claim retries; a refinement is a NEW claim and therefore a newly
|
|
46
|
+
* issued target. If a target ever did go stale, the consumer's version check
|
|
47
|
+
* refuses the artifact. The failure mode is a refusal, never an admitted
|
|
48
|
+
* unverified value.
|
|
49
|
+
*
|
|
50
|
+
* A hub that projects no `owes[].version` (pre-version-aware) yields
|
|
51
|
+
* `undefined`, and the caller submits unsigned rather than signing a guess.
|
|
52
|
+
*
|
|
53
|
+
* A target is only authoritative when it is a positive integer: the smallest
|
|
54
|
+
* commit any producer can land is v1, so 0 (or anything non-integral) is not a
|
|
55
|
+
* target this protocol issued — it is a pre-target-semantics hub or a corrupt
|
|
56
|
+
* packet. Both are treated as absent metadata and submit unsigned, rather than
|
|
57
|
+
* signing a number the consumer is guaranteed to reject.
|
|
33
58
|
*/
|
|
34
59
|
export declare function outputVersionForSubmission(order: OrderPacket, path: string, explicit?: number): number | undefined;
|
|
35
60
|
/** Reset the process-local warning latch for hermetic tests. */
|
|
@@ -64,19 +64,45 @@ function submissionFingerprint(order, warn) {
|
|
|
64
64
|
}
|
|
65
65
|
/**
|
|
66
66
|
* Resolve the version named by the next submission from authoritative lifecycle
|
|
67
|
-
* metadata only
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
*
|
|
67
|
+
* metadata only — never from a process-local guess.
|
|
68
|
+
*
|
|
69
|
+
* Three sources, in precedence order:
|
|
70
|
+
*
|
|
71
|
+
* 1. `explicit` — a caller-supplied target, used verbatim.
|
|
72
|
+
* 2. A judge approval attests the already-submitted version captured in the
|
|
73
|
+
* claim fingerprint and does not increment it (the engine's judge-approve
|
|
74
|
+
* branch flips acceptance without bumping `version`).
|
|
75
|
+
* 3. A producer submit uses `owes[].version`, the target the hub issued for
|
|
76
|
+
* this owed output inside the claim transaction. It is the version the
|
|
77
|
+
* next successful commit lands, which is exactly what the consumer checks
|
|
78
|
+
* the proof against.
|
|
79
|
+
*
|
|
80
|
+
* Retry-safety comes from the hub, not from this function. The target is
|
|
81
|
+
* computed once inside the claim transaction and persisted with the immutable
|
|
82
|
+
* order, so every retry of the same claim — a reconnect, a lost response, a
|
|
83
|
+
* restarted holder — reads the same number. The engine's refusal paths that
|
|
84
|
+
* leave the run open (schema-reject) do not bump the artifact, so the target
|
|
85
|
+
* survives in-claim retries; a refinement is a NEW claim and therefore a newly
|
|
86
|
+
* issued target. If a target ever did go stale, the consumer's version check
|
|
87
|
+
* refuses the artifact. The failure mode is a refusal, never an admitted
|
|
88
|
+
* unverified value.
|
|
89
|
+
*
|
|
90
|
+
* A hub that projects no `owes[].version` (pre-version-aware) yields
|
|
91
|
+
* `undefined`, and the caller submits unsigned rather than signing a guess.
|
|
92
|
+
*
|
|
93
|
+
* A target is only authoritative when it is a positive integer: the smallest
|
|
94
|
+
* commit any producer can land is v1, so 0 (or anything non-integral) is not a
|
|
95
|
+
* target this protocol issued — it is a pre-target-semantics hub or a corrupt
|
|
96
|
+
* packet. Both are treated as absent metadata and submit unsigned, rather than
|
|
97
|
+
* signing a number the consumer is guaranteed to reject.
|
|
73
98
|
*/
|
|
74
99
|
export function outputVersionForSubmission(order, path, explicit) {
|
|
75
100
|
if (explicit !== undefined)
|
|
76
101
|
return explicit;
|
|
77
102
|
if (order.judge === path)
|
|
78
103
|
return order.consumedFingerprint?.[path];
|
|
79
|
-
|
|
104
|
+
const target = order.owes?.find((owed) => owed.path === path)?.version;
|
|
105
|
+
return typeof target === 'number' && Number.isInteger(target) && target > 0 ? target : undefined;
|
|
80
106
|
}
|
|
81
107
|
function errorMessage(error) {
|
|
82
108
|
return error instanceof Error ? error.message : String(error);
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Producer-side mirror of the hub's raw-string submit normalization.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS EXISTS — the proof-dropping bug it fixes:
|
|
5
|
+
*
|
|
6
|
+
* An agent may hand `submit` a JSON-encoded STRING instead of an object
|
|
7
|
+
* (`'{"prUrl":"…","number":145}'`). The hub accepts that as a documented
|
|
8
|
+
* fallback: `hub-core`'s `submitOutput` runs `normalizeSubmitValue` on it and
|
|
9
|
+
* stores the resulting OBJECT. But because the stored bytes are no longer the
|
|
10
|
+
* bytes the producer signed, the hub cannot claim the signature covers what it
|
|
11
|
+
* stored, so it drops the submission proof outright:
|
|
12
|
+
*
|
|
13
|
+
* const narrowedProof = typeof rawValue === 'string' ? undefined
|
|
14
|
+
* : narrowSubmitProof(proof);
|
|
15
|
+
*
|
|
16
|
+
* The drop is silent on both sides. The producer signed successfully and got no
|
|
17
|
+
* warning; the hub committed the artifact with no proof. A downstream COMMAND
|
|
18
|
+
* step consuming that artifact then refuses it forever (`hardRule: true`), and
|
|
19
|
+
* nothing in either log says why. Observed live: the delivery `pr` artifact
|
|
20
|
+
* committed unproven while `workspace` — produced by an `exec` step, which
|
|
21
|
+
* always submits an object receipt — carried its proof fine.
|
|
22
|
+
*
|
|
23
|
+
* THE FIX: normalize here, before signing and before sending, so the producer
|
|
24
|
+
* signs exactly the object the hub will store and the hub never takes its
|
|
25
|
+
* string branch. This function is a deliberate byte-for-byte mirror of
|
|
26
|
+
* `owenloop-service` `packages/hub-core/src/normalize-submit-value.ts`; the two
|
|
27
|
+
* must agree, because any divergence produces a signature over bytes the hub
|
|
28
|
+
* did not store, which the consumer then rejects.
|
|
29
|
+
*
|
|
30
|
+
* A string this function cannot normalize is passed through UNCHANGED to the
|
|
31
|
+
* hub, which rejects it with `artifact-normalization-failed` exactly as it does
|
|
32
|
+
* today. Refusing locally would invent a failure mode the protocol does not
|
|
33
|
+
* have and would hide the hub's own diagnostic text from the agent.
|
|
34
|
+
*/
|
|
35
|
+
/**
|
|
36
|
+
* The value to sign and send for `raw`.
|
|
37
|
+
*
|
|
38
|
+
* Non-string input is returned as-is: only the string fallback triggers the
|
|
39
|
+
* hub's normalization, so only a string can desynchronize signed bytes from
|
|
40
|
+
* stored bytes.
|
|
41
|
+
*
|
|
42
|
+
* A string is repaired the way the hub repairs it — strip a surrounding
|
|
43
|
+
* ```json fence, escape bare control characters inside string literals, parse —
|
|
44
|
+
* and the parsed plain object is returned. Anything that fails to parse, or
|
|
45
|
+
* parses to a non-object (a bare number, an array, `null`), is returned as the
|
|
46
|
+
* original string so the hub renders its own verdict on it.
|
|
47
|
+
*/
|
|
48
|
+
export declare function normalizeSubmitValue(raw: unknown): unknown;
|