owenloop 0.5.0 → 0.5.1

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 (211) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +137 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +8 -4
  5. package/dist/packages/work/src/agent/brief.js +7 -3
  6. package/dist/packages/work/src/agent/loop.d.ts +13 -7
  7. package/dist/packages/work/src/agent/loop.js +136 -9
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +12 -1
  20. package/dist/packages/work/src/exec/loop.js +137 -20
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +74 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +27 -9
  38. package/dist/packages/work/src/harness/session-store.js +271 -67
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +126 -11
  41. package/dist/packages/work/src/hub/client.d.ts +2 -1
  42. package/dist/packages/work/src/hub/client.js +14 -1
  43. package/dist/packages/work/src/hub/types.d.ts +69 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +116 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +4 -0
  53. package/dist/packages/work/src/roles/hold.js +44 -5
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +5 -0
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +23 -1
  59. package/dist/packages/work/src/settings/settings.d.ts +17 -1
  60. package/dist/packages/work/src/settings/settings.js +39 -0
  61. package/dist/packages/work/src/shift/loop.d.ts +14 -3
  62. package/dist/packages/work/src/shift/loop.js +447 -164
  63. package/dist/packages/work/src/shift/protocol.d.ts +4 -0
  64. package/dist/packages/work/src/shift/runtime.d.ts +2 -0
  65. package/dist/packages/work/src/shift/runtime.js +66 -3
  66. package/dist/packages/work/src/shift/spawn.d.ts +41 -18
  67. package/dist/packages/work/src/shift/spawn.js +89 -31
  68. package/dist/packages/work/src/shift/state.d.ts +53 -51
  69. package/dist/packages/work/src/shift/state.js +325 -102
  70. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  71. package/dist/packages/work/src/submit-proof.js +93 -0
  72. package/dist/src/add.d.ts +64 -259
  73. package/dist/src/add.js +81 -615
  74. package/dist/src/archive.d.ts +97 -0
  75. package/dist/src/archive.js +591 -0
  76. package/dist/src/bundle/index.d.ts +64 -0
  77. package/dist/src/bundle/index.js +508 -0
  78. package/dist/src/bundle/manifest.d.ts +50 -0
  79. package/dist/src/bundle/manifest.js +435 -0
  80. package/dist/src/bundle/runtime.d.ts +26 -0
  81. package/dist/src/bundle/runtime.js +64 -0
  82. package/dist/src/bundle/tar.d.ts +62 -0
  83. package/dist/src/bundle/tar.js +238 -0
  84. package/dist/src/bundle/types.d.ts +105 -0
  85. package/dist/src/bundle/types.js +21 -0
  86. package/dist/src/cli.d.ts +90 -20
  87. package/dist/src/cli.js +2407 -365
  88. package/dist/src/credentials.d.ts +4 -3
  89. package/dist/src/credentials.js +21 -19
  90. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  91. package/dist/src/crypto/allowed-signers.js +307 -0
  92. package/dist/src/crypto/canonical.d.ts +8 -0
  93. package/dist/src/crypto/canonical.js +92 -0
  94. package/dist/src/crypto/chain.d.ts +65 -0
  95. package/dist/src/crypto/chain.js +377 -0
  96. package/dist/src/crypto/dsse.d.ts +209 -0
  97. package/dist/src/crypto/dsse.js +282 -0
  98. package/dist/src/crypto/enrollment.d.ts +78 -0
  99. package/dist/src/crypto/enrollment.js +186 -0
  100. package/dist/src/crypto/index.d.ts +48 -0
  101. package/dist/src/crypto/index.js +44 -0
  102. package/dist/src/crypto/keys.d.ts +258 -0
  103. package/dist/src/crypto/keys.js +908 -0
  104. package/dist/src/crypto/org-root.d.ts +33 -0
  105. package/dist/src/crypto/org-root.js +78 -0
  106. package/dist/src/crypto/origin-rules.d.ts +56 -0
  107. package/dist/src/crypto/origin-rules.js +143 -0
  108. package/dist/src/crypto/policy-floor.d.ts +98 -0
  109. package/dist/src/crypto/policy-floor.js +353 -0
  110. package/dist/src/crypto/records.d.ts +316 -0
  111. package/dist/src/crypto/records.js +157 -0
  112. package/dist/src/crypto/scope.d.ts +49 -0
  113. package/dist/src/crypto/scope.js +83 -0
  114. package/dist/src/crypto/ssh.d.ts +171 -0
  115. package/dist/src/crypto/ssh.js +396 -0
  116. package/dist/src/crypto/submission.d.ts +33 -0
  117. package/dist/src/crypto/submission.js +47 -0
  118. package/dist/src/crypto/trust-roots.d.ts +29 -0
  119. package/dist/src/crypto/trust-roots.js +39 -0
  120. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  121. package/dist/src/crypto/verify-consumed.js +259 -0
  122. package/dist/src/crypto/verify-origin.d.ts +50 -0
  123. package/dist/src/crypto/verify-origin.js +151 -0
  124. package/dist/src/crypto/verify-publication.d.ts +60 -0
  125. package/dist/src/crypto/verify-publication.js +150 -0
  126. package/dist/src/defs.d.ts +24 -1
  127. package/dist/src/defs.js +145 -25
  128. package/dist/src/engine.d.ts +99 -3
  129. package/dist/src/engine.js +238 -34
  130. package/dist/src/factory.d.ts +16 -0
  131. package/dist/src/factory.js +16 -4
  132. package/dist/src/global-config.d.ts +59 -0
  133. package/dist/src/global-config.js +84 -0
  134. package/dist/src/hub.d.ts +75 -21
  135. package/dist/src/hub.js +123 -40
  136. package/dist/src/index.d.ts +17 -2
  137. package/dist/src/index.js +20 -2
  138. package/dist/src/install.d.ts +538 -0
  139. package/dist/src/install.js +1981 -0
  140. package/dist/src/lock.d.ts +15 -57
  141. package/dist/src/lock.js +251 -143
  142. package/dist/src/mcp/serve.d.ts +46 -22
  143. package/dist/src/mcp/serve.js +167 -44
  144. package/dist/src/mcp/server.js +12 -1
  145. package/dist/src/model.d.ts +15 -0
  146. package/dist/src/model.js +111 -1
  147. package/dist/src/order-resolver.d.ts +184 -0
  148. package/dist/src/order-resolver.js +252 -0
  149. package/dist/src/package-version.d.ts +10 -0
  150. package/dist/src/package-version.js +42 -0
  151. package/dist/src/paths.d.ts +14 -1
  152. package/dist/src/paths.js +18 -0
  153. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  154. package/dist/src/schemas/index.d.ts +1416 -0
  155. package/dist/src/schemas/index.js +31 -0
  156. package/dist/src/schemas/order.v1.schema.json +106 -0
  157. package/dist/src/schemas/origin.v1.schema.json +68 -0
  158. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  159. package/dist/src/schemas/publication.v1.schema.json +31 -0
  160. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  161. package/dist/src/schemas/submission.v1.schema.json +61 -0
  162. package/dist/src/store/def-source.d.ts +52 -0
  163. package/dist/src/store/def-source.js +335 -0
  164. package/dist/src/store/index-file.d.ts +69 -0
  165. package/dist/src/store/index-file.js +151 -0
  166. package/dist/src/store/index.d.ts +27 -0
  167. package/dist/src/store/index.js +22 -0
  168. package/dist/src/store/ingestor.d.ts +43 -0
  169. package/dist/src/store/ingestor.js +211 -0
  170. package/dist/src/store/install.d.ts +228 -0
  171. package/dist/src/store/install.js +555 -0
  172. package/dist/src/store/instruction-source.d.ts +49 -0
  173. package/dist/src/store/instruction-source.js +298 -0
  174. package/dist/src/store/origin-evidence.d.ts +21 -0
  175. package/dist/src/store/origin-evidence.js +66 -0
  176. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  177. package/dist/src/store/pre-commit-verifier.js +418 -0
  178. package/dist/src/store/resolve.d.ts +138 -0
  179. package/dist/src/store/resolve.js +363 -0
  180. package/dist/src/store/types.d.ts +288 -0
  181. package/dist/src/store/types.js +356 -0
  182. package/dist/src/types.d.ts +45 -11
  183. package/dist/src/untar.d.ts +8 -23
  184. package/dist/src/untar.js +10 -136
  185. package/docs/agent-runner.md +86 -0
  186. package/docs/authoring.md +57 -6
  187. package/docs/bundles.md +250 -0
  188. package/docs/cli.md +1171 -97
  189. package/docs/crypto.md +816 -0
  190. package/docs/design.md +342 -20
  191. package/docs/embedding.md +132 -25
  192. package/docs/wire-contracts.md +380 -0
  193. package/package.json +6 -1
  194. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  195. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  196. package/plugins/claude-code/plugin/.mcp.json +14 -0
  197. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  198. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  199. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  200. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  201. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  202. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  203. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  204. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  205. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  206. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  207. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  208. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  209. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  210. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  211. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -11,16 +11,21 @@
11
11
  * claims survive a session drain). The loop's first `get_order` beats the
12
12
  * lease and delivers the order packet via `onOrder`; the loop then keeps the
13
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.
14
+ * 2. VALIDATE — a `null` packet, a non-`command` worker, or a missing/empty
15
+ * `owes` list is a MISROUTE (plan decision 3): not exec's to fail (a Step
16
+ * Agent could legitimately run it), so a targeted release, no submit, exit 1.
17
+ * A command worker's `defDigest` is then resolved through the verified local
18
+ * workflow store. Missing or corrupt instructions are a named refusal, not a
19
+ * misroute, and no child process is started.
18
20
  * 3. RUN + RACE — the runner shells the command out while the lease loop runs.
19
21
  * 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).
22
+ * - an ordinary command settles (any exit code, or a machinery error) ⇒
23
+ * build a receipt and `submit` it to every owed path. A payload reject
24
+ * follows those submits. Exit 0 means the receipt/reject delivery won;
25
+ * the receipt's exit code still carries the command result.
26
+ * - a judge command exits 0 ⇒ submit its receipt; a non-zero exit ⇒ send
27
+ * `reject` for `order.judge` without a receipt; signal or machinery
28
+ * failure ⇒ no verdict, leave the claim for the reap path.
24
29
  * - lease goes terminal first (lease-lost / ownership-error / unreachable /
25
30
  * the engine closed the run) ⇒ kill the command's process group, NO
26
31
  * submit (a submit would race the re-offer), exit 1.
@@ -35,7 +40,9 @@
35
40
  */
36
41
  import { createHash } from 'node:crypto';
37
42
  import { createLeaseLoop } from "../lease/loop.js";
43
+ import { parsePayloadLine } from "./payload.js";
38
44
  import { buildReceipt } from "./receipt.js";
45
+ import { buildSubmitProof } from "../submit-proof.js";
39
46
  /** sha256 of the empty byte string — the hash for a run with no captured output. */
40
47
  const EMPTY_HASH = createHash('sha256').digest('hex');
41
48
  function errMsg(e) {
@@ -109,8 +116,33 @@ export function createExecLoop(opts) {
109
116
  return 'hub-unreachable';
110
117
  return 'lease-lost';
111
118
  }
119
+ /** Deliver one reject verb and settle the lease after the response arrives. */
120
+ async function issueReject(path, text, successOutcome) {
121
+ try {
122
+ const res = await hub.reject({ workflow, run: runId, path, text });
123
+ if (res.ok !== true) {
124
+ opts.err(`owenloop work exec: reject of ${path} was refused: ${res.text}`);
125
+ lease.stop('reject-failed', res.closed === true ? { release: false } : undefined);
126
+ await leasePromise;
127
+ return 'reject-failed';
128
+ }
129
+ // A closed response means the hub already ended the claiming run. For a
130
+ // non-closed reject, release the still-open claim before this worker exits.
131
+ lease.stop(successOutcome, res.closed === true ? { release: false } : undefined);
132
+ await leasePromise;
133
+ return successOutcome;
134
+ }
135
+ catch (e) {
136
+ opts.err(`owenloop work exec: reject of ${path} failed: ${errMsg(e)}`);
137
+ // Receipts, when any, are already committed. Do not retry blindly or
138
+ // pretend the reject landed.
139
+ lease.stop('reject-failed');
140
+ await leasePromise;
141
+ return 'reject-failed';
142
+ }
143
+ }
112
144
  /** Build the receipt and submit it to every owed path. */
113
- async function submitReceipt(result, order) {
145
+ async function submitReceipt(result, order, resolvedCommand) {
114
146
  if (signalled) {
115
147
  // The operator killed the work and the command settled before the lease
116
148
  // (the release HTTP round-trip is slower than a TERM'd child dying), so
@@ -121,17 +153,65 @@ export function createExecLoop(opts) {
121
153
  await leasePromise;
122
154
  return 'killed';
123
155
  }
156
+ const parsedPayload = parsePayloadLine(result.payloadLine, result.payloadOverCap);
157
+ if (order.judge !== undefined) {
158
+ if (result.exitCode === null) {
159
+ // A signal or machinery failure is not a verdict. Leave the claim for
160
+ // the engine's reap path rather than releasing a silent judgement.
161
+ opts.err(`owenloop work exec: judge ${order.judge} ended without a verdict`);
162
+ lease.stop('judge-no-verdict', { release: false });
163
+ await leasePromise;
164
+ return 'judge-no-verdict';
165
+ }
166
+ if (result.exitCode !== 0) {
167
+ // Judge payload directives are deliberately ignored: one judge order
168
+ // has one verdict, and the command exit code supplies that verdict.
169
+ let text = result.outputTail;
170
+ if (parsedPayload.payload !== undefined && typeof parsedPayload.payload === 'object' && parsedPayload.payload !== null && !Array.isArray(parsedPayload.payload)) {
171
+ const reason = parsedPayload.payload['reason'];
172
+ if (typeof reason === 'string' && reason.trim() !== '')
173
+ text = reason;
174
+ }
175
+ if (text === '')
176
+ text = `judge command exited with code ${result.exitCode}`;
177
+ return issueReject(order.judge, text, 'judge-rejected');
178
+ }
179
+ }
124
180
  const receipt = buildReceipt(result, {
125
- command: order.command ?? '',
181
+ command: resolvedCommand,
126
182
  orchestrator: opts.holder.id,
127
183
  workflow,
128
184
  run: runId,
129
185
  step: order.step,
130
- });
186
+ }, parsedPayload);
131
187
  for (const owe of order.owes) {
132
188
  let res;
133
189
  try {
134
- res = await hub.submit({ workflow, run: runId, path: owe.path, value: receipt, holder: opts.holder });
190
+ let proof;
191
+ if (opts.origin !== undefined) {
192
+ // The immutable order can authorize a judge proof only when the owed
193
+ // path is the fingerprinted judged artifact. Producer command receipts
194
+ // remain unsigned until the hub issues a retry-safe target version.
195
+ proof = await buildSubmitProof({
196
+ origin: opts.origin,
197
+ order,
198
+ path: owe.path,
199
+ value: receipt,
200
+ now: opts.now,
201
+ warn: opts.err,
202
+ ...(opts.principalKeys !== undefined ? { principalKeys: opts.principalKeys } : {}),
203
+ ...(opts.env !== undefined ? { env: opts.env } : {}),
204
+ ...(opts.sshProcess !== undefined ? { sshProcess: opts.sshProcess } : {}),
205
+ });
206
+ }
207
+ res = await hub.submit({
208
+ workflow,
209
+ run: runId,
210
+ path: owe.path,
211
+ value: receipt,
212
+ ...(proof !== undefined ? { proof } : {}),
213
+ holder: opts.holder,
214
+ });
135
215
  }
136
216
  catch (e) {
137
217
  opts.err(`owenloop work exec: submit to ${owe.path} failed: ${errMsg(e)}`);
@@ -150,6 +230,12 @@ export function createExecLoop(opts) {
150
230
  }
151
231
  opts.out(`owenloop work exec: submitted receipt to ${owe.path} (${outcome})`);
152
232
  }
233
+ if (order.judge === undefined && parsedPayload.reject !== undefined) {
234
+ // All owed submissions must land before invalidating a consumed input;
235
+ // rejection moves the consume fingerprint and would born-reject later
236
+ // submits from this run.
237
+ return issueReject(parsedPayload.reject.path, parsedPayload.reject.text, 'rejected');
238
+ }
153
239
  // Every owed path landed — the run has closed, so stop WITHOUT releasing.
154
240
  lease.stop('submitted', { release: false });
155
241
  await leasePromise;
@@ -166,25 +252,56 @@ export function createExecLoop(opts) {
166
252
  if (first.t === 'lease')
167
253
  return mapNoHold(first.o);
168
254
  const order = first.res.order;
169
- const command = order?.command;
170
255
  if (order === null ||
171
- typeof command !== 'string' ||
172
- command === '' ||
173
- (order.executor !== undefined && order.executor !== 'command') ||
256
+ order.worker !== 'command' ||
174
257
  !Array.isArray(order.owes) ||
175
258
  order.owes.length === 0) {
176
- opts.err(`owenloop work exec: ${workflow}/${runId} is not a runnable command order (misroute) — releasing`);
259
+ opts.err(`owenloop work exec: ${workflow}/${runId} is not a command order (misroute) — releasing`);
177
260
  lease.stop('misroute'); // targeted release — not exec's to fail
178
261
  await leasePromise;
179
262
  return 'misroute';
180
263
  }
264
+ let resolvedCommand;
265
+ let resolvedBundleDir;
266
+ try {
267
+ const resolved = await opts.instructions.resolveCommand(order);
268
+ if (!resolved.ok) {
269
+ opts.err(`owenloop work exec: ${resolved.reason}`);
270
+ lease.stop('unresolved-instructions');
271
+ await leasePromise;
272
+ return 'unresolved-instructions';
273
+ }
274
+ resolvedCommand = resolved.command;
275
+ resolvedBundleDir = resolved.bundleDir;
276
+ }
277
+ catch (e) {
278
+ opts.err(`owenloop work exec: instruction refusal (integrity) for ${workflow}/${runId} ` +
279
+ `defDigest '${order.defDigest}': ${errMsg(e)}`);
280
+ lease.stop('unresolved-instructions');
281
+ await leasePromise;
282
+ return 'unresolved-instructions';
283
+ }
181
284
  // Run the command and race it against the lease going terminal.
182
285
  let cmd;
183
286
  try {
184
- cmd = runner.start(command, { cwd: order.workdir ?? opts.cwd });
287
+ // spawn's env replaces the child environment. Start from the actual exec
288
+ // process environment so config-only opts.env cannot strip PATH/HOME, then
289
+ // explicitly remove bundle provenance for loose definitions.
290
+ const childEnv = { ...process.env };
291
+ if (resolvedBundleDir === undefined)
292
+ delete childEnv['OWENLOOP_BUNDLE_DIR'];
293
+ else
294
+ childEnv['OWENLOOP_BUNDLE_DIR'] = resolvedBundleDir;
295
+ // Run identity is engine-derived from ExecLoopOptions, never a consumed
296
+ // artifact value, and always present. Overwrite inherited values so a
297
+ // nested exec sees its own identity rather than its parent's.
298
+ childEnv['OWENLOOP_WORKFLOW'] = workflow;
299
+ childEnv['OWENLOOP_RUN'] = runId;
300
+ const startOptions = { cwd: order.workdir ?? opts.cwd, env: childEnv };
301
+ cmd = runner.start(resolvedCommand, startOptions);
185
302
  }
186
303
  catch (e) {
187
- return submitReceipt(machineryFailure(e), order);
304
+ return submitReceipt(machineryFailure(e), order, resolvedCommand);
188
305
  }
189
306
  running = cmd;
190
307
  opts.out(`owenloop work exec: running ${workflow}/${runId} (step '${order.step}')`);
@@ -201,7 +318,7 @@ export function createExecLoop(opts) {
201
318
  opts.err(`owenloop work exec: lease ${outcome.o} while the command ran — killed the command, no receipt submitted`);
202
319
  return mapLeaseDuringRun(outcome.o);
203
320
  }
204
- return submitReceipt(outcome.r, order);
321
+ return submitReceipt(outcome.r, order, resolvedCommand);
205
322
  }
206
323
  function stop(reason) {
207
324
  if (signalled)
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The command payload channel. The runner only captures the bounded raw text
3
+ * after the marker; this module parses that text and validates the one
4
+ * worker-to-hub directive supported by exec.
5
+ */
6
+ /** The exact line prefix a command must print on stdout to emit a payload. */
7
+ export declare const PAYLOAD_MARKER = "##owenloop:payload##";
8
+ /** Maximum UTF-8 byte length of the JSON text after the marker. */
9
+ export declare const PAYLOAD_MAX_BYTES: number;
10
+ export interface RejectDirective {
11
+ path: string;
12
+ text: string;
13
+ }
14
+ export interface ParsedPayload {
15
+ /** Present when the marker contained valid JSON, including `null`/primitives. */
16
+ payload?: unknown;
17
+ /** Present when the marker or its reject directive could not be used. */
18
+ payloadError?: string;
19
+ /** Present only for a strictly valid reject directive. */
20
+ reject?: RejectDirective;
21
+ }
22
+ /**
23
+ * Parse the raw text after `PAYLOAD_MARKER`.
24
+ *
25
+ * `overCap` comes from the runner's bounded scanner. It is separate from the
26
+ * string because the scanner must not retain more than the cap just to report
27
+ * that a later byte made the line too large.
28
+ */
29
+ export declare function parsePayloadLine(payloadLine?: string, overCap?: boolean): ParsedPayload;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The command payload channel. The runner only captures the bounded raw text
3
+ * after the marker; this module parses that text and validates the one
4
+ * worker-to-hub directive supported by exec.
5
+ */
6
+ /** The exact line prefix a command must print on stdout to emit a payload. */
7
+ export const PAYLOAD_MARKER = '##owenloop:payload##';
8
+ /** Maximum UTF-8 byte length of the JSON text after the marker. */
9
+ export const PAYLOAD_MAX_BYTES = 64 * 1024;
10
+ function isRecord(value) {
11
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
12
+ }
13
+ function hasNonEmptyString(value) {
14
+ return typeof value === 'string' && value.trim().length > 0;
15
+ }
16
+ /**
17
+ * Parse the raw text after `PAYLOAD_MARKER`.
18
+ *
19
+ * `overCap` comes from the runner's bounded scanner. It is separate from the
20
+ * string because the scanner must not retain more than the cap just to report
21
+ * that a later byte made the line too large.
22
+ */
23
+ export function parsePayloadLine(payloadLine, overCap = false) {
24
+ if (overCap)
25
+ return { payloadError: `payload JSON exceeds the ${PAYLOAD_MAX_BYTES / 1024} KiB cap` };
26
+ if (payloadLine === undefined)
27
+ return {};
28
+ const jsonText = payloadLine.trim();
29
+ if (jsonText === '')
30
+ return { payloadError: 'payload marker has no JSON text' };
31
+ if (Buffer.byteLength(jsonText, 'utf8') > PAYLOAD_MAX_BYTES) {
32
+ return { payloadError: `payload JSON exceeds the ${PAYLOAD_MAX_BYTES / 1024} KiB cap` };
33
+ }
34
+ let payload;
35
+ try {
36
+ payload = JSON.parse(jsonText);
37
+ }
38
+ catch (error) {
39
+ const message = error instanceof Error ? error.message : String(error);
40
+ return { payloadError: `payload JSON is malformed: ${message}` };
41
+ }
42
+ if (!isRecord(payload) || !('reject' in payload))
43
+ return { payload };
44
+ const rawReject = payload['reject'];
45
+ if (!isRecord(rawReject)) {
46
+ return { payload, payloadError: 'payload reject directive must be an object' };
47
+ }
48
+ const path = rawReject['path'];
49
+ const text = rawReject['text'];
50
+ if (!hasNonEmptyString(path) || !hasNonEmptyString(text)) {
51
+ return { payload, payloadError: 'payload reject directive requires non-empty string path and text' };
52
+ }
53
+ return { payload, reject: { path, text } };
54
+ }
@@ -1,11 +1,12 @@
1
1
  /**
2
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.
3
+ * an ordinary command order, and for a judge order that exits 0. The hub `submit`
4
+ * verb has no failure channel, so a non-zero `exitCode` (or `exitCode: null` +
5
+ * `error` for machinery failure) carries the command result. A non-zero judge
6
+ * exit uses `reject` instead of a receipt, and signal-killed work submits neither.
7
+ * Pure construction so it is trivially asserted in tests.
8
8
  */
9
+ import { type ParsedPayload } from './payload.ts';
9
10
  import type { CommandResult } from './runner.ts';
10
11
  /** The submitted artifact value for a command order. */
11
12
  export interface CommandReceipt {
@@ -18,6 +19,8 @@ export interface CommandReceipt {
18
19
  stdoutBytes: number;
19
20
  stderrBytes: number;
20
21
  outputTail: string;
22
+ payload?: unknown;
23
+ payloadError?: string;
21
24
  startedAt: number;
22
25
  finishedAt: number;
23
26
  durationMs: number;
@@ -35,4 +38,4 @@ export interface ReceiptContext {
35
38
  step: string;
36
39
  }
37
40
  /** Fold a raw `CommandResult` and its order context into the submitted receipt. */
38
- export declare function buildReceipt(result: CommandResult, ctx: ReceiptContext): CommandReceipt;
41
+ export declare function buildReceipt(result: CommandResult, ctx: ReceiptContext, parsedPayload?: ParsedPayload): CommandReceipt;
@@ -1,5 +1,14 @@
1
+ /**
2
+ * The command receipt (C5, plan decision 8) — the audit record exec submits for
3
+ * an ordinary command order, and for a judge order that exits 0. The hub `submit`
4
+ * verb has no failure channel, so a non-zero `exitCode` (or `exitCode: null` +
5
+ * `error` for machinery failure) carries the command result. A non-zero judge
6
+ * exit uses `reject` instead of a receipt, and signal-killed work submits neither.
7
+ * Pure construction so it is trivially asserted in tests.
8
+ */
9
+ import { parsePayloadLine } from "./payload.js";
1
10
  /** Fold a raw `CommandResult` and its order context into the submitted receipt. */
2
- export function buildReceipt(result, ctx) {
11
+ export function buildReceipt(result, ctx, parsedPayload = parsePayloadLine(result.payloadLine, result.payloadOverCap)) {
3
12
  return {
4
13
  kind: 'command-receipt',
5
14
  command: ctx.command,
@@ -10,6 +19,8 @@ export function buildReceipt(result, ctx) {
10
19
  stdoutBytes: result.stdoutBytes,
11
20
  stderrBytes: result.stderrBytes,
12
21
  outputTail: result.outputTail,
22
+ ...('payload' in parsedPayload ? { payload: parsedPayload.payload } : {}),
23
+ ...(parsedPayload.payloadError !== undefined ? { payloadError: parsedPayload.payloadError } : {}),
13
24
  startedAt: result.startedAt,
14
25
  finishedAt: result.finishedAt,
15
26
  durationMs: result.durationMs,
@@ -16,6 +16,10 @@ export interface CommandResult {
16
16
  stderrBytes: number;
17
17
  /** Last ≤4 KiB of combined stdout+stderr, decoded lossily as UTF-8. */
18
18
  outputTail: string;
19
+ /** Raw text after the last matching stdout payload marker, before JSON parsing. */
20
+ payloadLine?: string;
21
+ /** True when the last matching marker line exceeded the payload cap. */
22
+ payloadOverCap?: boolean;
19
23
  startedAt: number;
20
24
  finishedAt: number;
21
25
  durationMs: number;
@@ -31,6 +35,7 @@ export interface RunningCommand {
31
35
  export interface CommandRunner {
32
36
  start(command: string, opts: {
33
37
  cwd: string;
38
+ env?: Record<string, string | undefined>;
34
39
  }): RunningCommand;
35
40
  }
36
41
  /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
@@ -41,6 +46,7 @@ export interface CommandPlan {
41
46
  cwd: string;
42
47
  detached: true;
43
48
  stdio: ['ignore', 'pipe', 'pipe'];
49
+ env?: Record<string, string | undefined>;
44
50
  };
45
51
  }
46
52
  /**
@@ -48,7 +54,7 @@ export interface CommandPlan {
48
54
  * spawn, no I/O — so tests assert the shape without launching anything. POSIX
49
55
  * `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
50
56
  */
51
- export declare function buildCommandPlan(command: string, cwd: string): CommandPlan;
57
+ export declare function buildCommandPlan(command: string, cwd: string, env?: Record<string, string | undefined>): CommandPlan;
52
58
  export interface DefaultRunnerOptions {
53
59
  /** SIGTERM→SIGKILL grace on a group kill (default 5_000). */
54
60
  graceMs?: number;
@@ -33,6 +33,7 @@
33
33
  */
34
34
  import { spawn } from 'node:child_process';
35
35
  import { createHash } from 'node:crypto';
36
+ import { PAYLOAD_MARKER, PAYLOAD_MAX_BYTES } from "./payload.js";
36
37
  const RETAIN_CAP_BYTES = 1024 * 1024; // 1 MiB retained per stream (for the tail)
37
38
  const TAIL_BYTES = 4096; // last 4 KiB of combined output kept in the receipt
38
39
  const DEFAULT_GRACE_MS = 5_000; // SIGTERM → grace → SIGKILL on a group kill
@@ -41,11 +42,21 @@ const DEFAULT_GRACE_MS = 5_000; // SIGTERM → grace → SIGKILL on a group kill
41
42
  * spawn, no I/O — so tests assert the shape without launching anything. POSIX
42
43
  * `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
43
44
  */
44
- export function buildCommandPlan(command, cwd) {
45
+ export function buildCommandPlan(command, cwd, env) {
46
+ // If a future package interpolates consumed values into command text or the
47
+ // child environment, that path must inherit resolveCommand's consume-side
48
+ // verification gate before this spawn plan is ever built. OWENLOOP_BUNDLE_DIR,
49
+ // when supplied by exec/loop.ts, is resolver-derived after that gate and is
50
+ // not a consumed artifact value.
45
51
  return {
46
52
  command: '/bin/sh',
47
53
  args: ['-c', command],
48
- options: { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] },
54
+ options: {
55
+ cwd,
56
+ detached: true,
57
+ stdio: ['ignore', 'pipe', 'pipe'],
58
+ ...(env !== undefined ? { env } : {}),
59
+ },
49
60
  };
50
61
  }
51
62
  /** Append `chunk` to a rolling tail buffer keeping only its last `cap` bytes. */
@@ -65,7 +76,7 @@ export function createDefaultRunner(opts = {}) {
65
76
  return {
66
77
  start(command, startOpts) {
67
78
  const startedAt = now();
68
- const plan = buildCommandPlan(command, startOpts.cwd);
79
+ const plan = buildCommandPlan(command, startOpts.cwd, startOpts.env);
69
80
  const hash = createHash('sha256'); // stdout-then-stderr, the ordered form
70
81
  const stderrHash = createHash('sha256'); // stderr alone — the degraded fallback
71
82
  let stdoutBytes = 0;
@@ -79,6 +90,61 @@ export function createDefaultRunner(opts = {}) {
79
90
  const pendingStderr = [];
80
91
  let pendingStderrBytes = 0;
81
92
  let degraded = false;
93
+ // Scan stdout lines independently of the bounded output tails. The
94
+ // scanner retains only the marker prefix plus the payload cap, so a
95
+ // command cannot force the runner to buffer an unbounded stream.
96
+ const payloadMarker = Buffer.from(PAYLOAD_MARKER, 'utf8');
97
+ const payloadLineCap = payloadMarker.length + PAYLOAD_MAX_BYTES + 1; // +1 detects overflow
98
+ let payloadLineBuffer = Buffer.alloc(0);
99
+ let payloadLineCapped = false;
100
+ let payloadLine;
101
+ let payloadOverCap = false;
102
+ const appendPayloadLine = (chunk) => {
103
+ if (payloadLineCapped || chunk.length === 0)
104
+ return;
105
+ const remaining = payloadLineCap - payloadLineBuffer.length;
106
+ if (chunk.length > remaining) {
107
+ payloadLineBuffer = Buffer.concat([payloadLineBuffer, chunk.subarray(0, remaining)]);
108
+ payloadLineCapped = true;
109
+ return;
110
+ }
111
+ payloadLineBuffer = Buffer.concat([payloadLineBuffer, chunk]);
112
+ };
113
+ const finishPayloadLine = () => {
114
+ if (payloadLineBuffer.length === 0)
115
+ return;
116
+ let line = payloadLineBuffer;
117
+ if (line[line.length - 1] === 0x0d)
118
+ line = line.subarray(0, line.length - 1);
119
+ if (line.length < payloadMarker.length || !line.subarray(0, payloadMarker.length).equals(payloadMarker)) {
120
+ payloadLineBuffer = Buffer.alloc(0);
121
+ payloadLineCapped = false;
122
+ return;
123
+ }
124
+ const rawPayload = line.subarray(payloadMarker.length);
125
+ if (payloadLineCapped || rawPayload.length > PAYLOAD_MAX_BYTES) {
126
+ payloadLine = undefined;
127
+ payloadOverCap = true;
128
+ }
129
+ else {
130
+ payloadLine = rawPayload.toString('utf8');
131
+ payloadOverCap = false;
132
+ }
133
+ payloadLineBuffer = Buffer.alloc(0);
134
+ payloadLineCapped = false;
135
+ };
136
+ const scanPayload = (chunk) => {
137
+ let offset = 0;
138
+ while (offset < chunk.length) {
139
+ const newline = chunk.indexOf(0x0a, offset);
140
+ const end = newline === -1 ? chunk.length : newline;
141
+ appendPayloadLine(chunk.subarray(offset, end));
142
+ if (newline === -1)
143
+ break;
144
+ finishPayloadLine();
145
+ offset = newline + 1;
146
+ }
147
+ };
82
148
  let settled = false;
83
149
  let resolveDone;
84
150
  const done = new Promise((r) => {
@@ -87,6 +153,7 @@ export function createDefaultRunner(opts = {}) {
87
153
  const finish = (exitCode, signal, error) => {
88
154
  if (settled)
89
155
  return;
156
+ finishPayloadLine();
90
157
  settled = true;
91
158
  // Flush any stderr that arrived before stdout ended, preserving the
92
159
  // stdout-then-stderr hash ordering (a no-op when degraded — dropped).
@@ -108,6 +175,8 @@ export function createDefaultRunner(opts = {}) {
108
175
  stdoutBytes,
109
176
  stderrBytes,
110
177
  outputTail: tail.toString('utf8'),
178
+ ...(payloadLine !== undefined ? { payloadLine } : {}),
179
+ ...(payloadOverCap ? { payloadOverCap: true } : {}),
111
180
  startedAt,
112
181
  finishedAt,
113
182
  durationMs: finishedAt - startedAt,
@@ -125,8 +194,10 @@ export function createDefaultRunner(opts = {}) {
125
194
  hash.update(chunk);
126
195
  stdoutBytes += chunk.length;
127
196
  stdoutTail = appendTail(stdoutTail, chunk, RETAIN_CAP_BYTES);
197
+ scanPayload(chunk);
128
198
  });
129
199
  child.stdout?.on('end', () => {
200
+ finishPayloadLine();
130
201
  stdoutEnded = true;
131
202
  if (!degraded)
132
203
  for (const c of pendingStderr)
@@ -89,6 +89,13 @@ export const ADMITTED_OWENLOOP_KEYS = new Set([
89
89
  // `resolveCacheDir` — src/bundle/cache.ts. Keeps anything the agent runs on
90
90
  // the same bundle cache as the worker. A path, not a secret.
91
91
  'OWENLOOP_CACHE_DIR',
92
+ // The step agent and anything it runs. Resolves bundle-shipped assets from
93
+ // the verified installed object directory. A path, not credential material.
94
+ 'OWENLOOP_BUNDLE_DIR',
95
+ // The step agent and anything it runs. Identifies the workflow instance.
96
+ 'OWENLOOP_WORKFLOW',
97
+ // The step agent and anything it runs. Identifies the current run.
98
+ 'OWENLOOP_RUN',
92
99
  // `holdShiftId` — src/roles/hold.ts. The fallback when `--shift=` is
93
100
  // absent from the mount's argv.
94
101
  'OWENLOOP_SHIFT_ID',
@@ -1,5 +1,5 @@
1
- import type { Options, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
- import type { AgentEvent, HarnessAdapter, StepPermissions } from './contract.ts';
1
+ import type { Options, Query, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
+ import type { AgentEvent, HarnessAdapter, HarnessSessionRef, StartArgs, StepPermissions } from './contract.ts';
3
3
  /**
4
4
  * Build the environment the harness child runs under.
5
5
  *
@@ -65,8 +65,7 @@ export declare function allowApiBillingFrom(source: Record<string, string | unde
65
65
  * and the `PATH` searched are the same ones the child will see.
66
66
  */
67
67
  export declare function resolveExecutable(source: Record<string, string | undefined>): string | undefined;
68
- /** Everything `buildClaudeOptions` reads off a start. `deliver` gets only `cwd`
69
- * and `owenloopMcp` from the contract, so it passes an empty permission set. */
68
+ /** Everything `buildClaudeOptions` reads for either cold start or resume. */
70
69
  export interface ClaudeOptionInputs {
71
70
  cwd: string;
72
71
  owenloopMcp: {
@@ -86,6 +85,8 @@ export interface ClaudeOptionExtras {
86
85
  env: Record<string, string | undefined>;
87
86
  abortController: AbortController;
88
87
  onEvent: (e: AgentEvent) => void;
88
+ /** Preselected UUID for a cold start. Never set on a resume. */
89
+ sessionId?: string;
89
90
  /** Set on a resume only. Never set on a start. */
90
91
  resume?: string;
91
92
  }
@@ -98,6 +99,16 @@ export interface ClaudeOptionExtras {
98
99
  * direction.
99
100
  */
100
101
  export declare function buildClaudeOptions(inputs: ClaudeOptionInputs, extra: ClaudeOptionExtras): Options;
102
+ export type ClaudeQuery = AsyncIterable<SDKMessage> & Pick<Query, 'close'>;
103
+ export interface ClaudeQueryArgs {
104
+ prompt: string;
105
+ options: Options;
106
+ }
107
+ export type ClaudeQueryFactory = (args: ClaudeQueryArgs) => ClaudeQuery;
108
+ export interface ClaudeStartDependencies {
109
+ createSessionId: () => string;
110
+ loadQuery: () => Promise<ClaudeQueryFactory>;
111
+ }
101
112
  /** What one consumed turn tells the caller. */
102
113
  export interface TurnOutcome {
103
114
  /** The session id from the `system/init` message, if one arrived. */
@@ -111,9 +122,9 @@ export interface TurnOutcome {
111
122
  * Resolves at the `result` message — turn end, per the contract — not at process
112
123
  * exit, and regardless of whether the result reports an error.
113
124
  *
114
- * `onInit` fires the instant the session id is known, so `start` can emit
115
- * `{kind:'started'}` BEFORE it resolves: the caller persists the token on that
116
- * event, which is what leaves a resumable record behind after a mid-turn crash.
125
+ * `onInit` fires after a matching `system/init` confirms the preselected cold-
126
+ * start session id. `startClaude` emits `{kind:'started'}` before query creation;
127
+ * this callback marks the later provider confirmation, not the persistence gate.
117
128
  *
118
129
  * PHASE 6, ITEM 1 — EXPORTED, AND TYPED ON `AsyncIterable` RATHER THAN `Query`.
119
130
  * This is the one function that maps the SDK's message stream onto this
@@ -124,5 +135,6 @@ export interface TurnOutcome {
124
135
  * what it uses is what lets a fixture drive it. A live `Query` still satisfies
125
136
  * the narrower type, so nothing at the call sites changes.
126
137
  */
127
- export declare function consumeTurn(q: AsyncIterable<SDKMessage>, onEvent: (e: AgentEvent) => void, onInit?: (sessionId: string) => void): Promise<TurnOutcome>;
138
+ export declare function consumeTurn(q: AsyncIterable<SDKMessage>, onEvent: (e: AgentEvent) => void, onInit?: (sessionId: string) => void, expectedSessionId?: string): Promise<TurnOutcome>;
139
+ export declare function startClaude(args: StartArgs, onEvent: (e: AgentEvent) => void, dependencies?: ClaudeStartDependencies): Promise<HarnessSessionRef>;
128
140
  export declare const claudeAdapter: HarnessAdapter;