owenloop 0.5.1 → 0.5.2

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 (81) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  13. package/dist/packages/work/src/harness/session-store.js +46 -22
  14. package/dist/packages/work/src/hold/mcp.js +9 -2
  15. package/dist/packages/work/src/hub/client.d.ts +7 -1
  16. package/dist/packages/work/src/hub/client.js +1 -0
  17. package/dist/packages/work/src/hub/types.d.ts +71 -3
  18. package/dist/packages/work/src/roles/agent-run.js +8 -9
  19. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  20. package/dist/packages/work/src/roles/hold.js +39 -8
  21. package/dist/packages/work/src/roles/settings.js +18 -6
  22. package/dist/packages/work/src/roles/shift.js +13 -1
  23. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  24. package/dist/packages/work/src/settings/settings.js +69 -22
  25. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  26. package/dist/packages/work/src/shift/logretention.js +407 -0
  27. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  28. package/dist/packages/work/src/shift/logsink.js +98 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  30. package/dist/packages/work/src/shift/loop.js +250 -12
  31. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  32. package/dist/packages/work/src/shift/protocol.js +14 -0
  33. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  34. package/dist/packages/work/src/shift/runtime.js +229 -6
  35. package/dist/packages/work/src/shift/server.d.ts +13 -0
  36. package/dist/packages/work/src/shift/server.js +61 -36
  37. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  38. package/dist/packages/work/src/shift/spawn.js +158 -12
  39. package/dist/packages/work/src/shift/state.d.ts +25 -0
  40. package/dist/packages/work/src/shift/state.js +29 -5
  41. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  42. package/dist/packages/work/src/shift/truncate.js +73 -0
  43. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  44. package/dist/packages/work/src/submit-proof.js +33 -7
  45. package/dist/packages/work/src/submit-value.d.ts +48 -0
  46. package/dist/packages/work/src/submit-value.js +118 -0
  47. package/dist/packages/work/src/usage.d.ts +1 -1
  48. package/dist/packages/work/src/usage.js +11 -0
  49. package/dist/src/capabilities.d.ts +93 -0
  50. package/dist/src/capabilities.js +101 -0
  51. package/dist/src/cli.js +14 -9
  52. package/dist/src/crypto/records.d.ts +3 -0
  53. package/dist/src/crypto/records.js +11 -0
  54. package/dist/src/defs.js +192 -4
  55. package/dist/src/engine.d.ts +112 -3
  56. package/dist/src/engine.js +224 -28
  57. package/dist/src/hub.d.ts +27 -11
  58. package/dist/src/hub.js +24 -18
  59. package/dist/src/index.d.ts +3 -1
  60. package/dist/src/index.js +4 -1
  61. package/dist/src/mcp/serve.js +11 -4
  62. package/dist/src/model.d.ts +36 -0
  63. package/dist/src/model.js +46 -0
  64. package/dist/src/schemas/index.d.ts +17 -0
  65. package/dist/src/schemas/order.v1.schema.json +17 -3
  66. package/dist/src/store.d.ts +33 -1
  67. package/dist/src/store.js +57 -4
  68. package/dist/src/types.d.ts +102 -2
  69. package/docs/authoring.md +7 -0
  70. package/docs/bundles.md +103 -3
  71. package/docs/cli.md +127 -9
  72. package/docs/crypto.md +23 -7
  73. package/docs/shift-logs.md +642 -0
  74. package/docs/wire-contracts.md +34 -19
  75. package/package.json +1 -1
  76. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  77. package/plugins/claude-code/plugin/.mcp.json +1 -1
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  81. 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
- * all stdio ignored, `unref()` — so the child is its own process-group leader and
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
- const child = spawn(plan.command, plan.args, plan.options);
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
- // No worker stdio slot is a parent-owned pipe. Once Shift exits, a detached
97
- // worker may keep writing diagnostics without receiving EPIPE from a vanished
98
- // reader. Agent-run stderr is untrusted; exec failures therefore use the same
99
- // bounded generic lifecycle message rather than capturing worker output.
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 join(xdg, 'owenloop', 'exec');
36
+ return resolve(xdg, 'owenloop', 'exec');
22
37
  const home = env['HOME'];
23
38
  if (home !== undefined && home.trim() !== '')
24
- return join(home, '.local', 'state', 'owenloop', 'exec');
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
- function safeRun(run) {
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. A judge approval attests the already-submitted version captured
28
- * in the claim fingerprint and does not increment it. A producer submit requires
29
- * an explicit target version issued by a retry-safe hub protocol: `owes[].version`
30
- * is immutable claim-time state and becomes stale after a refinement, lost
31
- * response, unsigned commit, or holder restart. Without an explicit target,
32
- * callers must submit without a proof rather than sign a process-local guess.
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. A judge approval attests the already-submitted version captured
68
- * in the claim fingerprint and does not increment it. A producer submit requires
69
- * an explicit target version issued by a retry-safe hub protocol: `owes[].version`
70
- * is immutable claim-time state and becomes stale after a refinement, lost
71
- * response, unsigned commit, or holder restart. Without an explicit target,
72
- * callers must submit without a proof rather than sign a process-local guess.
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
- return undefined;
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;