owenloop 0.4.1 → 0.5.0

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 (154) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +58 -31
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{cli.d.ts → src/cli.d.ts} +18 -3
  109. package/dist/{cli.js → src/cli.js} +770 -114
  110. package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
  111. package/dist/{credentials.js → src/credentials.js} +14 -12
  112. package/dist/{defs.js → src/defs.js} +36 -36
  113. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  114. package/dist/{engine.js → src/engine.js} +14 -14
  115. package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
  116. package/dist/{hub.js → src/hub.js} +370 -12
  117. package/dist/{index.d.ts → src/index.d.ts} +1 -1
  118. package/dist/{index.js → src/index.js} +1 -1
  119. package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
  120. package/dist/{mcp → src/mcp}/serve.js +168 -31
  121. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  122. package/dist/{mcp → src/mcp}/server.js +6 -9
  123. package/dist/{model.js → src/model.js} +1 -1
  124. package/dist/{types.d.ts → src/types.d.ts} +18 -18
  125. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  126. package/dist/{util.js → src/util.js} +3 -2
  127. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  128. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  129. package/docs/authoring.md +93 -53
  130. package/docs/cli.md +597 -76
  131. package/docs/design.md +33 -33
  132. package/docs/embedding.md +10 -9
  133. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  134. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  135. package/examples/workflows/judges/gate-sharpness.md +39 -0
  136. package/examples/workflows/judges/security.md +34 -0
  137. package/package.json +17 -8
  138. /package/dist/{add.d.ts → src/add.d.ts} +0 -0
  139. /package/dist/{add.js → src/add.js} +0 -0
  140. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  141. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  142. /package/dist/{factory.js → src/factory.js} +0 -0
  143. /package/dist/{lock.d.ts → src/lock.d.ts} +0 -0
  144. /package/dist/{lock.js → src/lock.js} +0 -0
  145. /package/dist/{model.d.ts → src/model.d.ts} +0 -0
  146. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  147. /package/dist/{paths.js → src/paths.js} +0 -0
  148. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  149. /package/dist/{schema.js → src/schema.js} +0 -0
  150. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  151. /package/dist/{store.js → src/store.js} +0 -0
  152. /package/dist/{types.js → src/types.js} +0 -0
  153. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  154. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -0,0 +1,56 @@
1
+ /**
2
+ * The ONE place the bearer-token resolution / refuse / dev-override logic lives,
3
+ * so all five roles share identical precedence instead of re-deriving it:
4
+ *
5
+ * 1. `OWENLOOP_TOKEN` (trimmed, non-empty) — an EXPLICIT dev-only override.
6
+ * When set, it is used verbatim and the store + account are skipped.
7
+ * 2. Otherwise read the `agent:<account>` slot from owenloop's store:
8
+ * - a `Credential` → its bearer token (`credentialToToken`).
9
+ * - `null` → refuse (code 2): no Scoped Identity key for this origin/account,
10
+ * naming a runnable `owenloop login` connect command.
11
+ * - a THROW → error (code 1): a genuine read failure (bad origin /
12
+ * external-command failure), surfaced with its message.
13
+ *
14
+ * The refuse (code 2) is a refuse-to-start precondition, mirroring the old
15
+ * "no token" exit code, so existing exit-code assertions stay valid — only the
16
+ * message text changes. owenloop stays read-only w.r.t. credentials.
17
+ */
18
+ import { OwenloopCredentialReader } from "./owenloop.js";
19
+ import { credentialToToken } from "./reader.js";
20
+ /**
21
+ * The owenloop `--as <slot>` argument for an account: `agent` for the default
22
+ * account, `agent:<account>` otherwise. Grounded from owenloop's `--as`
23
+ * semantics (`human` | `agent` | `agent:<account>`).
24
+ */
25
+ export function slotArg(account) {
26
+ return account === 'default' ? 'agent' : `agent:${account}`;
27
+ }
28
+ export async function resolveBearer(args) {
29
+ const { origin, account, env } = args;
30
+ // 1. Dev-only override: explicit OWENLOOP_TOKEN bypasses the store + account.
31
+ const override = env['OWENLOOP_TOKEN']?.trim();
32
+ if (override !== undefined && override !== '') {
33
+ return { ok: true, token: override };
34
+ }
35
+ // 2. The store: read ONLY the agent:<account> slot (never human).
36
+ let cred;
37
+ try {
38
+ cred = await new OwenloopCredentialReader({ account, env }).read(origin);
39
+ }
40
+ catch (err) {
41
+ const detail = err instanceof Error ? err.message : String(err);
42
+ return {
43
+ ok: false,
44
+ code: 1,
45
+ message: `credential read failed for ${origin} (account "${account}"): ${detail}`,
46
+ };
47
+ }
48
+ if (cred === null) {
49
+ return {
50
+ ok: false,
51
+ code: 2,
52
+ message: `no Scoped Identity key for ${origin} (account "${account}") — run: owenloop login --hub ${origin} --as ${slotArg(account)}`,
53
+ };
54
+ }
55
+ return { ok: true, token: credentialToToken(cred) };
56
+ }
@@ -0,0 +1,29 @@
1
+ import type { HubClient } from '../hub/client.ts';
2
+ import type { ContactHolder } from '../hub/types.ts';
3
+ import type { CommandRunner } from './runner.ts';
4
+ /** Discriminated result of an exec run; the role maps these to exit codes. */
5
+ export type ExecOutcome = 'submitted' | 'completed' | 'misroute' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'submit-rejected' | 'submit-failed' | 'stopped';
6
+ export interface ExecLoopOptions {
7
+ hub: HubClient;
8
+ runner: CommandRunner;
9
+ workflow: string;
10
+ run: string;
11
+ /** The exec process holder tag `{kind:'exec', id}` — id is `<hostname>:<pid>`. */
12
+ holder: ContactHolder;
13
+ /** cwd for the command when the order packet carries no `workdir`. */
14
+ cwd: string;
15
+ sleep: (ms: number) => Promise<void>;
16
+ now: () => number;
17
+ random?: () => number;
18
+ out: (line: string) => void;
19
+ err: (line: string) => void;
20
+ heartbeatIntervalMs?: number;
21
+ jumpToleranceMs?: number;
22
+ failureWindowMs?: number;
23
+ }
24
+ export interface ExecLoop {
25
+ run(): Promise<ExecOutcome>;
26
+ /** Final breath: kill the command group and release. Wired to SIGINT/SIGTERM. */
27
+ stop(reason?: string): void;
28
+ }
29
+ export declare function createExecLoop(opts: ExecLoopOptions): ExecLoop;
@@ -0,0 +1,215 @@
1
+ /**
2
+ * The exec orchestration core (C5) — the detached, self-leasing command worker.
3
+ *
4
+ * A command order the shift (C3) dispatched becomes a detached `owenloop work exec`
5
+ * process. This core drives its whole life against the hub, every side effect
6
+ * injected (hub client, command runner, sleep/clock, output sinks) so tests run
7
+ * it with a fake hub + fake runner and no real timers or child processes:
8
+ *
9
+ * 1. FIRST CONTACT — starts the shared lease loop (`src/lease/loop.ts`) with the
10
+ * exec holder tag `{kind:'exec', id}` (the B3 drain exemption: exec-held
11
+ * claims survive a session drain). The loop's first `get_order` beats the
12
+ * lease and delivers the order packet via `onOrder`; the loop then keeps the
13
+ * lease warm underneath everything below.
14
+ * 2. VALIDATE — a `null` packet, a missing/blank `command`, a non-`command`
15
+ * executor, or a missing/empty `owes` is a MISROUTE (plan decision 3): not exec's to
16
+ * fail (a Step Agent could legitimately run it), so a targeted release, no
17
+ * submit, exit 1.
18
+ * 3. RUN + RACE — the runner shells the command out while the lease loop runs.
19
+ * Whichever settles first wins (plan decision 9):
20
+ * - command settles (any exit code, or a machinery error) ⇒ build a
21
+ * receipt and `submit` it to every owed path, then stop the lease
22
+ * WITHOUT release (the run just closed). Exit 0 — delivering the receipt
23
+ * IS the job, even for a failing command (the exit code carries truth).
24
+ * - lease goes terminal first (lease-lost / ownership-error / unreachable /
25
+ * the engine closed the run) ⇒ kill the command's process group, NO
26
+ * submit (a submit would race the re-offer), exit 1.
27
+ * 4. FINAL BREATH — a SIGINT/SIGTERM aimed at exec itself is an operator killing
28
+ * the work (drain only exempts exec from the SESSION's death): `stop()` kills
29
+ * the command group and takes a targeted release, exit 1 (plan decision 1).
30
+ * Killed work NEVER gets a receipt — even when the TERM'd command settles
31
+ * before the release round-trip resolves the lease (the common ordering),
32
+ * the submit path checks `signalled` and bails to `killed`.
33
+ *
34
+ * The role (`src/roles/exec.ts`) maps each `ExecOutcome` to an exit code.
35
+ */
36
+ import { createHash } from 'node:crypto';
37
+ import { createLeaseLoop } from "../lease/loop.js";
38
+ import { buildReceipt } from "./receipt.js";
39
+ /** sha256 of the empty byte string — the hash for a run with no captured output. */
40
+ const EMPTY_HASH = createHash('sha256').digest('hex');
41
+ function errMsg(e) {
42
+ return e instanceof Error ? e.message : String(e);
43
+ }
44
+ export function createExecLoop(opts) {
45
+ const { hub, runner, workflow } = opts;
46
+ const runId = opts.run;
47
+ let running;
48
+ let signalled = false;
49
+ let leasePromise;
50
+ let resolveOrder;
51
+ const orderReady = new Promise((r) => {
52
+ resolveOrder = r;
53
+ });
54
+ const lease = createLeaseLoop({
55
+ hub,
56
+ workflow,
57
+ run: runId,
58
+ role: 'exec',
59
+ holder: opts.holder,
60
+ onOrder: (res) => resolveOrder?.(res),
61
+ sleep: opts.sleep,
62
+ now: opts.now,
63
+ out: opts.out,
64
+ err: opts.err,
65
+ ...(opts.random !== undefined ? { random: opts.random } : {}),
66
+ ...(opts.heartbeatIntervalMs !== undefined ? { heartbeatIntervalMs: opts.heartbeatIntervalMs } : {}),
67
+ ...(opts.jumpToleranceMs !== undefined ? { jumpToleranceMs: opts.jumpToleranceMs } : {}),
68
+ ...(opts.failureWindowMs !== undefined ? { failureWindowMs: opts.failureWindowMs } : {}),
69
+ });
70
+ /** A CommandResult standing in for a runner that threw before producing one. */
71
+ function machineryFailure(e) {
72
+ const t = opts.now();
73
+ return {
74
+ exitCode: null,
75
+ error: errMsg(e),
76
+ outputHash: `sha256:${EMPTY_HASH}`,
77
+ stdoutBytes: 0,
78
+ stderrBytes: 0,
79
+ outputTail: '',
80
+ startedAt: t,
81
+ finishedAt: t,
82
+ durationMs: 0,
83
+ };
84
+ }
85
+ /** A first-contact / no-hold lease outcome → exec outcome. */
86
+ function mapNoHold(o) {
87
+ switch (o) {
88
+ case 'completed':
89
+ return 'completed';
90
+ case 'ownership-error':
91
+ return 'ownership-error';
92
+ case 'hub-unreachable':
93
+ return 'hub-unreachable';
94
+ case 'lease-lost':
95
+ return 'lease-lost';
96
+ case 'stopped':
97
+ return signalled ? 'killed' : 'stopped';
98
+ case 'released':
99
+ case 'release-failed':
100
+ // stop() with release fired before the hold was ever established.
101
+ return 'killed';
102
+ }
103
+ }
104
+ /** A lease outcome observed while the command was running (exit 1 always). */
105
+ function mapLeaseDuringRun(o) {
106
+ if (o === 'ownership-error')
107
+ return 'ownership-error';
108
+ if (o === 'hub-unreachable')
109
+ return 'hub-unreachable';
110
+ return 'lease-lost';
111
+ }
112
+ /** Build the receipt and submit it to every owed path. */
113
+ async function submitReceipt(result, order) {
114
+ if (signalled) {
115
+ // The operator killed the work and the command settled before the lease
116
+ // (the release HTTP round-trip is slower than a TERM'd child dying), so
117
+ // the done branch won the race. Plan decision 1: NO receipt for killed
118
+ // work — a submit here would race the release/re-offer. stop() already
119
+ // took the targeted release; just wait for it.
120
+ opts.err(`owenloop work exec: signalled — killed work gets no receipt, released ${workflow}/${runId}`);
121
+ await leasePromise;
122
+ return 'killed';
123
+ }
124
+ const receipt = buildReceipt(result, {
125
+ command: order.command ?? '',
126
+ orchestrator: opts.holder.id,
127
+ workflow,
128
+ run: runId,
129
+ step: order.step,
130
+ });
131
+ for (const owe of order.owes) {
132
+ let res;
133
+ try {
134
+ res = await hub.submit({ workflow, run: runId, path: owe.path, value: receipt, holder: opts.holder });
135
+ }
136
+ catch (e) {
137
+ opts.err(`owenloop work exec: submit to ${owe.path} failed: ${errMsg(e)}`);
138
+ lease.stop('submit-failed'); // targeted release (idempotent) — best effort
139
+ await leasePromise;
140
+ return 'submit-failed';
141
+ }
142
+ const outcome = res.outcome;
143
+ if (outcome !== 'green' && outcome !== 'submitted') {
144
+ opts.err(`owenloop work exec: submit to ${owe.path} rejected (${outcome ?? 'unknown'}): ${res.text}`);
145
+ // born-rejected ⇒ the claim is already gone, no release; otherwise a
146
+ // targeted release is idempotent and harmless.
147
+ lease.stop('submit-rejected', outcome === 'born-rejected' ? { release: false } : undefined);
148
+ await leasePromise;
149
+ return 'submit-rejected';
150
+ }
151
+ opts.out(`owenloop work exec: submitted receipt to ${owe.path} (${outcome})`);
152
+ }
153
+ // Every owed path landed — the run has closed, so stop WITHOUT releasing.
154
+ lease.stop('submitted', { release: false });
155
+ await leasePromise;
156
+ return 'submitted';
157
+ }
158
+ async function run() {
159
+ leasePromise = lease.run();
160
+ // First contact race: the order arrives (hold established), or the lease
161
+ // resolves terminally before we ever established it.
162
+ const first = await Promise.race([
163
+ orderReady.then((res) => ({ t: 'order', res })),
164
+ leasePromise.then((o) => ({ t: 'lease', o })),
165
+ ]);
166
+ if (first.t === 'lease')
167
+ return mapNoHold(first.o);
168
+ const order = first.res.order;
169
+ const command = order?.command;
170
+ if (order === null ||
171
+ typeof command !== 'string' ||
172
+ command === '' ||
173
+ (order.executor !== undefined && order.executor !== 'command') ||
174
+ !Array.isArray(order.owes) ||
175
+ order.owes.length === 0) {
176
+ opts.err(`owenloop work exec: ${workflow}/${runId} is not a runnable command order (misroute) — releasing`);
177
+ lease.stop('misroute'); // targeted release — not exec's to fail
178
+ await leasePromise;
179
+ return 'misroute';
180
+ }
181
+ // Run the command and race it against the lease going terminal.
182
+ let cmd;
183
+ try {
184
+ cmd = runner.start(command, { cwd: order.workdir ?? opts.cwd });
185
+ }
186
+ catch (e) {
187
+ return submitReceipt(machineryFailure(e), order);
188
+ }
189
+ running = cmd;
190
+ opts.out(`owenloop work exec: running ${workflow}/${runId} (step '${order.step}')`);
191
+ const outcome = await Promise.race([
192
+ cmd.done.then((r) => ({ t: 'done', r })).catch((e) => ({ t: 'done', r: machineryFailure(e) })),
193
+ leasePromise.then((o) => ({ t: 'lease', o })),
194
+ ]);
195
+ if (outcome.t === 'lease') {
196
+ await cmd.kill(); // no receipt — a submit now would race the re-offer
197
+ if (signalled) {
198
+ opts.err(`owenloop work exec: signalled mid-run — killed the command group, released ${workflow}/${runId}`);
199
+ return 'killed';
200
+ }
201
+ opts.err(`owenloop work exec: lease ${outcome.o} while the command ran — killed the command, no receipt submitted`);
202
+ return mapLeaseDuringRun(outcome.o);
203
+ }
204
+ return submitReceipt(outcome.r, order);
205
+ }
206
+ function stop(reason) {
207
+ if (signalled)
208
+ return;
209
+ signalled = true;
210
+ if (running !== undefined)
211
+ void running.kill();
212
+ lease.stop(reason ?? 'signal'); // release:true — hand the killed order back
213
+ }
214
+ return { run, stop };
215
+ }
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The command receipt (C5, plan decision 8) — the audit record exec submits for
3
+ * a command order. It IS the result contract: the hub `submit` verb has no
4
+ * failure channel, so a receipt is submitted for EVERY finished command — a
5
+ * non-zero `exitCode` (or `exitCode: null` + `error` for machinery failure)
6
+ * carries the truth, and exec still exits 0 because its job (deliver the
7
+ * receipt) succeeded. Pure construction so it is trivially asserted in tests.
8
+ */
9
+ import type { CommandResult } from './runner.ts';
10
+ /** The submitted artifact value for a command order. */
11
+ export interface CommandReceipt {
12
+ kind: 'command-receipt';
13
+ command: string;
14
+ exitCode: number | null;
15
+ signal?: string;
16
+ error?: string;
17
+ outputHash: string;
18
+ stdoutBytes: number;
19
+ stderrBytes: number;
20
+ outputTail: string;
21
+ startedAt: number;
22
+ finishedAt: number;
23
+ durationMs: number;
24
+ /** The holder id of the exec process that ran it (`<hostname>:<pid>`). */
25
+ orchestrator: string;
26
+ workflow: string;
27
+ run: string;
28
+ step: string;
29
+ }
30
+ export interface ReceiptContext {
31
+ command: string;
32
+ orchestrator: string;
33
+ workflow: string;
34
+ run: string;
35
+ step: string;
36
+ }
37
+ /** Fold a raw `CommandResult` and its order context into the submitted receipt. */
38
+ export declare function buildReceipt(result: CommandResult, ctx: ReceiptContext): CommandReceipt;
@@ -0,0 +1,21 @@
1
+ /** Fold a raw `CommandResult` and its order context into the submitted receipt. */
2
+ export function buildReceipt(result, ctx) {
3
+ return {
4
+ kind: 'command-receipt',
5
+ command: ctx.command,
6
+ exitCode: result.exitCode,
7
+ ...(result.signal !== undefined ? { signal: result.signal } : {}),
8
+ ...(result.error !== undefined ? { error: result.error } : {}),
9
+ outputHash: result.outputHash,
10
+ stdoutBytes: result.stdoutBytes,
11
+ stderrBytes: result.stderrBytes,
12
+ outputTail: result.outputTail,
13
+ startedAt: result.startedAt,
14
+ finishedAt: result.finishedAt,
15
+ durationMs: result.durationMs,
16
+ orchestrator: ctx.orchestrator,
17
+ workflow: ctx.workflow,
18
+ run: ctx.run,
19
+ step: ctx.step,
20
+ };
21
+ }
@@ -0,0 +1,65 @@
1
+ /** The raw execution facts a run produces; the loop wraps these into a receipt. */
2
+ export interface CommandResult {
3
+ /** The command's exit code, or `null` when killed by signal / machinery failed. */
4
+ exitCode: number | null;
5
+ /** The signal that terminated the command, when it was signalled. */
6
+ signal?: string;
7
+ /** Set only on execution-machinery failure (spawn/cwd/error) — not a non-zero exit. */
8
+ error?: string;
9
+ /**
10
+ * `sha256:<hex>` over full stdout bytes then full stderr bytes, or — when
11
+ * out-of-order stderr overflowed the 1 MiB buffer cap — the two-part
12
+ * `sha256:<stdout hex>+<stderr hex>` (each stream hashed fully on its own).
13
+ */
14
+ outputHash: string;
15
+ stdoutBytes: number;
16
+ stderrBytes: number;
17
+ /** Last ≤4 KiB of combined stdout+stderr, decoded lossily as UTF-8. */
18
+ outputTail: string;
19
+ startedAt: number;
20
+ finishedAt: number;
21
+ durationMs: number;
22
+ }
23
+ /** A command that is running (or has failed to start). */
24
+ export interface RunningCommand {
25
+ /** Resolves once the command settles (any exit code, kill, or machinery error). */
26
+ done: Promise<CommandResult>;
27
+ /** Idempotently take down the command's process group (TERM → grace → KILL). */
28
+ kill(): Promise<void>;
29
+ }
30
+ /** The runner seam. Injected into the exec loop; faked in the loop's tests. */
31
+ export interface CommandRunner {
32
+ start(command: string, opts: {
33
+ cwd: string;
34
+ }): RunningCommand;
35
+ }
36
+ /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
37
+ export interface CommandPlan {
38
+ command: string;
39
+ args: string[];
40
+ options: {
41
+ cwd: string;
42
+ detached: true;
43
+ stdio: ['ignore', 'pipe', 'pipe'];
44
+ };
45
+ }
46
+ /**
47
+ * Build the argv + options for a detached `/bin/sh -c <command>`. Pure — no
48
+ * spawn, no I/O — so tests assert the shape without launching anything. POSIX
49
+ * `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
50
+ */
51
+ export declare function buildCommandPlan(command: string, cwd: string): CommandPlan;
52
+ export interface DefaultRunnerOptions {
53
+ /** SIGTERM→SIGKILL grace on a group kill (default 5_000). */
54
+ graceMs?: number;
55
+ /** Clock seam (default `Date.now`). */
56
+ now?: () => number;
57
+ /** Timer seam for the kill grace (default real `setTimeout`). */
58
+ sleep?: (ms: number) => Promise<void>;
59
+ }
60
+ /**
61
+ * The default command runner: spawns `/bin/sh -c <command>` in its own process
62
+ * group and captures a bounded result. Every timing/timer seam is injectable so
63
+ * the kill-grace path is testable without wall-clock waits.
64
+ */
65
+ export declare function createDefaultRunner(opts?: DefaultRunnerOptions): CommandRunner;
@@ -0,0 +1,185 @@
1
+ /**
2
+ * The command-runner seam (C5, plan decision 7).
3
+ *
4
+ * exec's one job that actually touches the machine: shell out the order's opaque
5
+ * `command` string, capture its result, and — on a kill — take down the whole
6
+ * process group. It is a SEAM so the exec loop's tests drive a fake runner and
7
+ * never spawn a real child; only `exec-runner.test.ts` exercises the default
8
+ * impl, against harmless fixtures in a test-created temp cwd.
9
+ *
10
+ * The default runner spawns `/bin/sh -c <command>` DETACHED (its own process
11
+ * group, so a group-kill reaches every descendant the command forks) with
12
+ * stdout/stderr piped. It captures:
13
+ * - `outputHash`: sha256 over the FULL stdout bytes then the FULL stderr bytes
14
+ * (in that order): `sha256:<hex>`. To hash the full streams in that order
15
+ * with bounded live memory, stdout is fed to the hash as it arrives and
16
+ * stderr chunks that arrive before stdout ends are buffered, then flushed in
17
+ * order. That out-of-order buffer is CAPPED at 1 MiB (a long command
18
+ * streaming progress to stderr while stdout stays open would otherwise
19
+ * buffer its entire stderr — an OOM vector). On overflow the capture
20
+ * degrades deterministically to the two-part form
21
+ * `sha256:<sha256(full stdout)>+<sha256(full stderr)>` — both streams still
22
+ * fully hashed, only the interleaved ordering claim is dropped, and the
23
+ * hash string itself says which form it is. Memory stays bounded either way.
24
+ * - `outputTail`: the last 4 KiB of the combined (stdout-then-stderr) output,
25
+ * decoded lossily as UTF-8 — enough for a human to eyeball a failure without
26
+ * bloating the submitted receipt (each retained tail buffer is itself capped
27
+ * at 1 MiB). Binary / no-trailing-newline output is fine: the tail is a lossy
28
+ * excerpt, the hash is over raw bytes.
29
+ *
30
+ * Execution-machinery failure (spawn ENOENT, a missing cwd, an `error` event)
31
+ * resolves — never rejects — with `exitCode: null` and an `error` string, so the
32
+ * exec loop can submit a receipt for it (plan decision 2) rather than crashing.
33
+ */
34
+ import { spawn } from 'node:child_process';
35
+ import { createHash } from 'node:crypto';
36
+ const RETAIN_CAP_BYTES = 1024 * 1024; // 1 MiB retained per stream (for the tail)
37
+ const TAIL_BYTES = 4096; // last 4 KiB of combined output kept in the receipt
38
+ const DEFAULT_GRACE_MS = 5_000; // SIGTERM → grace → SIGKILL on a group kill
39
+ /**
40
+ * Build the argv + options for a detached `/bin/sh -c <command>`. Pure — no
41
+ * spawn, no I/O — so tests assert the shape without launching anything. POSIX
42
+ * `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
43
+ */
44
+ export function buildCommandPlan(command, cwd) {
45
+ return {
46
+ command: '/bin/sh',
47
+ args: ['-c', command],
48
+ options: { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] },
49
+ };
50
+ }
51
+ /** Append `chunk` to a rolling tail buffer keeping only its last `cap` bytes. */
52
+ function appendTail(buf, chunk, cap) {
53
+ const next = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
54
+ return next.length > cap ? next.subarray(next.length - cap) : next;
55
+ }
56
+ /**
57
+ * The default command runner: spawns `/bin/sh -c <command>` in its own process
58
+ * group and captures a bounded result. Every timing/timer seam is injectable so
59
+ * the kill-grace path is testable without wall-clock waits.
60
+ */
61
+ export function createDefaultRunner(opts = {}) {
62
+ const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
63
+ const now = opts.now ?? Date.now;
64
+ const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
65
+ return {
66
+ start(command, startOpts) {
67
+ const startedAt = now();
68
+ const plan = buildCommandPlan(command, startOpts.cwd);
69
+ const hash = createHash('sha256'); // stdout-then-stderr, the ordered form
70
+ const stderrHash = createHash('sha256'); // stderr alone — the degraded fallback
71
+ let stdoutBytes = 0;
72
+ let stderrBytes = 0;
73
+ let stdoutTail = Buffer.alloc(0);
74
+ let stderrTail = Buffer.alloc(0);
75
+ let stdoutEnded = false;
76
+ // stderr that arrived before stdout ended, held to preserve the ordered
77
+ // hash — CAPPED: on overflow we drop it and degrade to the two-part hash
78
+ // (`hash` then covers stdout only; `stderrHash` always covers all stderr).
79
+ const pendingStderr = [];
80
+ let pendingStderrBytes = 0;
81
+ let degraded = false;
82
+ let settled = false;
83
+ let resolveDone;
84
+ const done = new Promise((r) => {
85
+ resolveDone = r;
86
+ });
87
+ const finish = (exitCode, signal, error) => {
88
+ if (settled)
89
+ return;
90
+ settled = true;
91
+ // Flush any stderr that arrived before stdout ended, preserving the
92
+ // stdout-then-stderr hash ordering (a no-op when degraded — dropped).
93
+ if (!degraded)
94
+ for (const c of pendingStderr)
95
+ hash.update(c);
96
+ pendingStderr.length = 0;
97
+ pendingStderrBytes = 0;
98
+ const finishedAt = now();
99
+ const combined = Buffer.concat([stdoutTail, stderrTail]);
100
+ const tail = combined.length > TAIL_BYTES ? combined.subarray(combined.length - TAIL_BYTES) : combined;
101
+ resolveDone({
102
+ exitCode,
103
+ ...(signal !== null ? { signal } : {}),
104
+ ...(error !== undefined ? { error } : {}),
105
+ outputHash: degraded
106
+ ? `sha256:${hash.digest('hex')}+${stderrHash.digest('hex')}`
107
+ : `sha256:${hash.digest('hex')}`,
108
+ stdoutBytes,
109
+ stderrBytes,
110
+ outputTail: tail.toString('utf8'),
111
+ startedAt,
112
+ finishedAt,
113
+ durationMs: finishedAt - startedAt,
114
+ });
115
+ };
116
+ let child;
117
+ try {
118
+ child = spawn(plan.command, plan.args, plan.options);
119
+ }
120
+ catch (e) {
121
+ finish(null, null, e instanceof Error ? e.message : String(e));
122
+ return { done, kill: async () => { } };
123
+ }
124
+ child.stdout?.on('data', (chunk) => {
125
+ hash.update(chunk);
126
+ stdoutBytes += chunk.length;
127
+ stdoutTail = appendTail(stdoutTail, chunk, RETAIN_CAP_BYTES);
128
+ });
129
+ child.stdout?.on('end', () => {
130
+ stdoutEnded = true;
131
+ if (!degraded)
132
+ for (const c of pendingStderr)
133
+ hash.update(c);
134
+ pendingStderr.length = 0;
135
+ pendingStderrBytes = 0;
136
+ });
137
+ child.stderr?.on('data', (chunk) => {
138
+ stderrHash.update(chunk); // always — this is the degraded fallback
139
+ if (!degraded) {
140
+ if (stdoutEnded) {
141
+ hash.update(chunk);
142
+ }
143
+ else if (pendingStderrBytes + chunk.length > RETAIN_CAP_BYTES) {
144
+ // Out-of-order stderr overflowed the cap: drop the held chunks and
145
+ // degrade — `hash` stays stdout-only, `stderrHash` has everything.
146
+ degraded = true;
147
+ pendingStderr.length = 0;
148
+ pendingStderrBytes = 0;
149
+ }
150
+ else {
151
+ pendingStderr.push(chunk);
152
+ pendingStderrBytes += chunk.length;
153
+ }
154
+ }
155
+ stderrBytes += chunk.length;
156
+ stderrTail = appendTail(stderrTail, chunk, RETAIN_CAP_BYTES);
157
+ });
158
+ child.on('error', (e) => finish(null, null, e.message));
159
+ child.on('close', (code, signal) => finish(code, signal));
160
+ const kill = async () => {
161
+ if (settled || child.pid === undefined)
162
+ return;
163
+ const pid = child.pid;
164
+ try {
165
+ process.kill(-pid, 'SIGTERM'); // negative pid → the whole process group
166
+ }
167
+ catch {
168
+ // Group already gone (raced the close) — nothing to signal.
169
+ return;
170
+ }
171
+ // Grace, then a hard SIGKILL if it is still alive.
172
+ await Promise.race([done, sleep(graceMs)]);
173
+ if (settled)
174
+ return;
175
+ try {
176
+ process.kill(-pid, 'SIGKILL');
177
+ }
178
+ catch {
179
+ // Gone between the grace and now — fine.
180
+ }
181
+ };
182
+ return { done, kill };
183
+ },
184
+ };
185
+ }