owenloop 0.4.1 → 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 (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  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/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /package/dist/{types.js → src/types.js} +0 -0
@@ -0,0 +1,256 @@
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
+ import { PAYLOAD_MARKER, PAYLOAD_MAX_BYTES } from "./payload.js";
37
+ const RETAIN_CAP_BYTES = 1024 * 1024; // 1 MiB retained per stream (for the tail)
38
+ const TAIL_BYTES = 4096; // last 4 KiB of combined output kept in the receipt
39
+ const DEFAULT_GRACE_MS = 5_000; // SIGTERM → grace → SIGKILL on a group kill
40
+ /**
41
+ * Build the argv + options for a detached `/bin/sh -c <command>`. Pure — no
42
+ * spawn, no I/O — so tests assert the shape without launching anything. POSIX
43
+ * `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
44
+ */
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.
51
+ return {
52
+ command: '/bin/sh',
53
+ args: ['-c', command],
54
+ options: {
55
+ cwd,
56
+ detached: true,
57
+ stdio: ['ignore', 'pipe', 'pipe'],
58
+ ...(env !== undefined ? { env } : {}),
59
+ },
60
+ };
61
+ }
62
+ /** Append `chunk` to a rolling tail buffer keeping only its last `cap` bytes. */
63
+ function appendTail(buf, chunk, cap) {
64
+ const next = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
65
+ return next.length > cap ? next.subarray(next.length - cap) : next;
66
+ }
67
+ /**
68
+ * The default command runner: spawns `/bin/sh -c <command>` in its own process
69
+ * group and captures a bounded result. Every timing/timer seam is injectable so
70
+ * the kill-grace path is testable without wall-clock waits.
71
+ */
72
+ export function createDefaultRunner(opts = {}) {
73
+ const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
74
+ const now = opts.now ?? Date.now;
75
+ const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
76
+ return {
77
+ start(command, startOpts) {
78
+ const startedAt = now();
79
+ const plan = buildCommandPlan(command, startOpts.cwd, startOpts.env);
80
+ const hash = createHash('sha256'); // stdout-then-stderr, the ordered form
81
+ const stderrHash = createHash('sha256'); // stderr alone — the degraded fallback
82
+ let stdoutBytes = 0;
83
+ let stderrBytes = 0;
84
+ let stdoutTail = Buffer.alloc(0);
85
+ let stderrTail = Buffer.alloc(0);
86
+ let stdoutEnded = false;
87
+ // stderr that arrived before stdout ended, held to preserve the ordered
88
+ // hash — CAPPED: on overflow we drop it and degrade to the two-part hash
89
+ // (`hash` then covers stdout only; `stderrHash` always covers all stderr).
90
+ const pendingStderr = [];
91
+ let pendingStderrBytes = 0;
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
+ };
148
+ let settled = false;
149
+ let resolveDone;
150
+ const done = new Promise((r) => {
151
+ resolveDone = r;
152
+ });
153
+ const finish = (exitCode, signal, error) => {
154
+ if (settled)
155
+ return;
156
+ finishPayloadLine();
157
+ settled = true;
158
+ // Flush any stderr that arrived before stdout ended, preserving the
159
+ // stdout-then-stderr hash ordering (a no-op when degraded — dropped).
160
+ if (!degraded)
161
+ for (const c of pendingStderr)
162
+ hash.update(c);
163
+ pendingStderr.length = 0;
164
+ pendingStderrBytes = 0;
165
+ const finishedAt = now();
166
+ const combined = Buffer.concat([stdoutTail, stderrTail]);
167
+ const tail = combined.length > TAIL_BYTES ? combined.subarray(combined.length - TAIL_BYTES) : combined;
168
+ resolveDone({
169
+ exitCode,
170
+ ...(signal !== null ? { signal } : {}),
171
+ ...(error !== undefined ? { error } : {}),
172
+ outputHash: degraded
173
+ ? `sha256:${hash.digest('hex')}+${stderrHash.digest('hex')}`
174
+ : `sha256:${hash.digest('hex')}`,
175
+ stdoutBytes,
176
+ stderrBytes,
177
+ outputTail: tail.toString('utf8'),
178
+ ...(payloadLine !== undefined ? { payloadLine } : {}),
179
+ ...(payloadOverCap ? { payloadOverCap: true } : {}),
180
+ startedAt,
181
+ finishedAt,
182
+ durationMs: finishedAt - startedAt,
183
+ });
184
+ };
185
+ let child;
186
+ try {
187
+ child = spawn(plan.command, plan.args, plan.options);
188
+ }
189
+ catch (e) {
190
+ finish(null, null, e instanceof Error ? e.message : String(e));
191
+ return { done, kill: async () => { } };
192
+ }
193
+ child.stdout?.on('data', (chunk) => {
194
+ hash.update(chunk);
195
+ stdoutBytes += chunk.length;
196
+ stdoutTail = appendTail(stdoutTail, chunk, RETAIN_CAP_BYTES);
197
+ scanPayload(chunk);
198
+ });
199
+ child.stdout?.on('end', () => {
200
+ finishPayloadLine();
201
+ stdoutEnded = true;
202
+ if (!degraded)
203
+ for (const c of pendingStderr)
204
+ hash.update(c);
205
+ pendingStderr.length = 0;
206
+ pendingStderrBytes = 0;
207
+ });
208
+ child.stderr?.on('data', (chunk) => {
209
+ stderrHash.update(chunk); // always — this is the degraded fallback
210
+ if (!degraded) {
211
+ if (stdoutEnded) {
212
+ hash.update(chunk);
213
+ }
214
+ else if (pendingStderrBytes + chunk.length > RETAIN_CAP_BYTES) {
215
+ // Out-of-order stderr overflowed the cap: drop the held chunks and
216
+ // degrade — `hash` stays stdout-only, `stderrHash` has everything.
217
+ degraded = true;
218
+ pendingStderr.length = 0;
219
+ pendingStderrBytes = 0;
220
+ }
221
+ else {
222
+ pendingStderr.push(chunk);
223
+ pendingStderrBytes += chunk.length;
224
+ }
225
+ }
226
+ stderrBytes += chunk.length;
227
+ stderrTail = appendTail(stderrTail, chunk, RETAIN_CAP_BYTES);
228
+ });
229
+ child.on('error', (e) => finish(null, null, e.message));
230
+ child.on('close', (code, signal) => finish(code, signal));
231
+ const kill = async () => {
232
+ if (settled || child.pid === undefined)
233
+ return;
234
+ const pid = child.pid;
235
+ try {
236
+ process.kill(-pid, 'SIGTERM'); // negative pid → the whole process group
237
+ }
238
+ catch {
239
+ // Group already gone (raced the close) — nothing to signal.
240
+ return;
241
+ }
242
+ // Grace, then a hard SIGKILL if it is still alive.
243
+ await Promise.race([done, sleep(graceMs)]);
244
+ if (settled)
245
+ return;
246
+ try {
247
+ process.kill(-pid, 'SIGKILL');
248
+ }
249
+ catch {
250
+ // Gone between the grace and now — fine.
251
+ }
252
+ };
253
+ return { done, kill };
254
+ },
255
+ };
256
+ }
@@ -0,0 +1,100 @@
1
+ /**
2
+ * PHASE 6, ITEMS 3 + 5 — the `OWENLOOP_*` namespace allowlist for harness
3
+ * children. Vendor-neutral by construction: this module names no harness and no
4
+ * vendor, only owenloop's own environment variables.
5
+ *
6
+ * ── WHAT THE FILTER DOES, EXACTLY ────────────────────────────────────────────
7
+ *
8
+ * It applies to variables whose name begins with `OWENLOOP_`, and to NOTHING
9
+ * else. Within that namespace only the names in `ADMITTED_OWENLOOP_KEYS` are
10
+ * passed to a harness child; every other `OWENLOOP_*` name is removed. Every
11
+ * variable OUTSIDE the namespace — `PATH`, `HOME`, `TMPDIR`, `LANG`,
12
+ * `SSL_CERT_FILE`, corporate proxy variables, `NODE_OPTIONS`, each vendor's own
13
+ * credential and configuration variables — passes through untouched.
14
+ *
15
+ * ── WHY THE SCOPE IS THE NAMESPACE AND NOT THE WHOLE ENVIRONMENT ─────────────
16
+ *
17
+ * Two requirements pull in opposite directions on one mechanism:
18
+ *
19
+ * ITEM 5 wants owenloop's dev-only hub bearer override to stop reaching
20
+ * harness children. A harness child is an ordinary process that inherits its
21
+ * parent's environment, and at least one harness demonstrably persists its
22
+ * start parameters to disk, so credential material in that environment has a
23
+ * real path to a file on the operator's machine.
24
+ *
25
+ * ITEM 3 wants a harness's own OAuth credential variable to KEEP reaching its
26
+ * child, because under launchd the Keychain read can fail and that variable is
27
+ * the fallback credential path. A stranded credential is a harness that cannot
28
+ * start at all.
29
+ *
30
+ * A conventional allowlist — "the child gets only the names on this list" —
31
+ * satisfies both only if the list is exhaustive over everything every vendor
32
+ * binary needs in order to start. That set is unknowable, and it grows with each
33
+ * vendor release. Scoping the allowlist to owenloop's OWN namespace makes the
34
+ * two requirements independent rather than opposed:
35
+ *
36
+ * - owenloop knows every name in the `OWENLOOP_*` namespace and every consumer
37
+ * of every name. That is exactly the knowledge a precise allowlist needs, and
38
+ * exactly the knowledge owenloop does not have about `PATH` or about a
39
+ * vendor's variables.
40
+ * - No vendor credential variable is in the namespace, so no vendor credential
41
+ * can be stranded — not by oversight, not by a later edit. Structurally.
42
+ * - It is still deny-by-default WITHIN the namespace, so an `OWENLOOP_*`
43
+ * variable added by some future phase does not silently start flowing to
44
+ * harness children. Adding one to this set is a deliberate, reviewable act.
45
+ *
46
+ * ── HOW THE ADMITTED SET WAS DERIVED, AND HOW TO RE-DERIVE IT ────────────────
47
+ *
48
+ * The only owenloop process a harness child spawns is the work-holder MCP mount
49
+ * (`owenloop work hold --mcp`), whose argv is built by `src/agent/brief.ts`. Walking
50
+ * the import graph from `src/roles/hold.ts` and collecting every reachable
51
+ * `OWENLOOP_*` read yields these holder inputs:
52
+ *
53
+ * - `OWENLOOP_SHIFT_ID` and `OWENLOOP_SESSION` from `src/roles/hold.ts`;
54
+ * - `OWENLOOP_CREDENTIAL_COMMAND`, `OWENLOOP_CREDENTIAL_COMMAND_TIMEOUT_MS`,
55
+ * and `OWENLOOP_NO_KEYCHAIN` from `src/hub.ts:readStoredCredential()`;
56
+ * - `OWENLOOP_TOKEN` from `src/credentials/resolve.ts`, which is DENIED on
57
+ * purpose — see below.
58
+ *
59
+ * The three credential controls are admitted because the mounted holder uses
60
+ * them to select and configure its credential backend before the MCP server
61
+ * starts. `src/hub.ts:runCredentialCommand()` creates
62
+ * `OWENLOOP_CREDENTIAL_ORIGIN` and `OWENLOOP_CREDENTIAL_SLOT` internally, so
63
+ * those two helper-only names are not inherited from the harness parent.
64
+ *
65
+ * `OWENLOOP_CACHE_DIR` is admitted although it is NOT reachable from `hold`: it
66
+ * is read by `resolveCacheDir` (`src/bundle/cache.ts`), which an agent reaches
67
+ * when its own work runs an owenloop subcommand that touches the bundle cache.
68
+ * It is a directory path, not credential material, and admitting it keeps the
69
+ * worker and anything the agent runs pointed at the same cache.
70
+ *
71
+ * ── THE ONE DENIAL WITH A DELIBERATE CONSEQUENCE ─────────────────────────────
72
+ *
73
+ * `OWENLOOP_TOKEN` is denied, and it IS reachable from `hold`. Left alone that
74
+ * would split the two sides apart: the worker would authenticate to the hub with
75
+ * the override while the child fell back to its credential slot, and an empty
76
+ * slot would surface mid-order as a confusing MCP handshake failure. So
77
+ * `src/roles/agent-run.ts` also ignores `OWENLOOP_TOKEN` when resolving its own
78
+ * bearer. Worker and child then agree, and the failure moves to startup, where
79
+ * `resolveBearer` already refuses with exit code 2 and an actionable message.
80
+ */
81
+ /**
82
+ * The `OWENLOOP_*` names a harness child may see. Everything else in the
83
+ * namespace is removed; everything outside the namespace is untouched.
84
+ *
85
+ * Each entry needs a named consumer that a harness child can actually reach. An
86
+ * entry with no such consumer is a leak with a comment on it.
87
+ */
88
+ export declare const ADMITTED_OWENLOOP_KEYS: ReadonlySet<string>;
89
+ /**
90
+ * A copy of `source` with every non-admitted `OWENLOOP_*` key removed.
91
+ *
92
+ * `source` is a parameter rather than a read of `process.env` so callers and
93
+ * tests can inject a fixture; the input is never mutated. Keys are `delete`d
94
+ * rather than set to `undefined`, because an own key holding `undefined` is not
95
+ * obviously equivalent to an absent key once it crosses a spawn or
96
+ * serialization boundary.
97
+ */
98
+ export declare function filterOwenloopEnv(source: Record<string, string | undefined>): Record<string, string | undefined>;
99
+ /** Whether one variable name may reach a harness child. */
100
+ export declare function isAdmittedChildEnvKey(key: string): boolean;
@@ -0,0 +1,134 @@
1
+ /**
2
+ * PHASE 6, ITEMS 3 + 5 — the `OWENLOOP_*` namespace allowlist for harness
3
+ * children. Vendor-neutral by construction: this module names no harness and no
4
+ * vendor, only owenloop's own environment variables.
5
+ *
6
+ * ── WHAT THE FILTER DOES, EXACTLY ────────────────────────────────────────────
7
+ *
8
+ * It applies to variables whose name begins with `OWENLOOP_`, and to NOTHING
9
+ * else. Within that namespace only the names in `ADMITTED_OWENLOOP_KEYS` are
10
+ * passed to a harness child; every other `OWENLOOP_*` name is removed. Every
11
+ * variable OUTSIDE the namespace — `PATH`, `HOME`, `TMPDIR`, `LANG`,
12
+ * `SSL_CERT_FILE`, corporate proxy variables, `NODE_OPTIONS`, each vendor's own
13
+ * credential and configuration variables — passes through untouched.
14
+ *
15
+ * ── WHY THE SCOPE IS THE NAMESPACE AND NOT THE WHOLE ENVIRONMENT ─────────────
16
+ *
17
+ * Two requirements pull in opposite directions on one mechanism:
18
+ *
19
+ * ITEM 5 wants owenloop's dev-only hub bearer override to stop reaching
20
+ * harness children. A harness child is an ordinary process that inherits its
21
+ * parent's environment, and at least one harness demonstrably persists its
22
+ * start parameters to disk, so credential material in that environment has a
23
+ * real path to a file on the operator's machine.
24
+ *
25
+ * ITEM 3 wants a harness's own OAuth credential variable to KEEP reaching its
26
+ * child, because under launchd the Keychain read can fail and that variable is
27
+ * the fallback credential path. A stranded credential is a harness that cannot
28
+ * start at all.
29
+ *
30
+ * A conventional allowlist — "the child gets only the names on this list" —
31
+ * satisfies both only if the list is exhaustive over everything every vendor
32
+ * binary needs in order to start. That set is unknowable, and it grows with each
33
+ * vendor release. Scoping the allowlist to owenloop's OWN namespace makes the
34
+ * two requirements independent rather than opposed:
35
+ *
36
+ * - owenloop knows every name in the `OWENLOOP_*` namespace and every consumer
37
+ * of every name. That is exactly the knowledge a precise allowlist needs, and
38
+ * exactly the knowledge owenloop does not have about `PATH` or about a
39
+ * vendor's variables.
40
+ * - No vendor credential variable is in the namespace, so no vendor credential
41
+ * can be stranded — not by oversight, not by a later edit. Structurally.
42
+ * - It is still deny-by-default WITHIN the namespace, so an `OWENLOOP_*`
43
+ * variable added by some future phase does not silently start flowing to
44
+ * harness children. Adding one to this set is a deliberate, reviewable act.
45
+ *
46
+ * ── HOW THE ADMITTED SET WAS DERIVED, AND HOW TO RE-DERIVE IT ────────────────
47
+ *
48
+ * The only owenloop process a harness child spawns is the work-holder MCP mount
49
+ * (`owenloop work hold --mcp`), whose argv is built by `src/agent/brief.ts`. Walking
50
+ * the import graph from `src/roles/hold.ts` and collecting every reachable
51
+ * `OWENLOOP_*` read yields these holder inputs:
52
+ *
53
+ * - `OWENLOOP_SHIFT_ID` and `OWENLOOP_SESSION` from `src/roles/hold.ts`;
54
+ * - `OWENLOOP_CREDENTIAL_COMMAND`, `OWENLOOP_CREDENTIAL_COMMAND_TIMEOUT_MS`,
55
+ * and `OWENLOOP_NO_KEYCHAIN` from `src/hub.ts:readStoredCredential()`;
56
+ * - `OWENLOOP_TOKEN` from `src/credentials/resolve.ts`, which is DENIED on
57
+ * purpose — see below.
58
+ *
59
+ * The three credential controls are admitted because the mounted holder uses
60
+ * them to select and configure its credential backend before the MCP server
61
+ * starts. `src/hub.ts:runCredentialCommand()` creates
62
+ * `OWENLOOP_CREDENTIAL_ORIGIN` and `OWENLOOP_CREDENTIAL_SLOT` internally, so
63
+ * those two helper-only names are not inherited from the harness parent.
64
+ *
65
+ * `OWENLOOP_CACHE_DIR` is admitted although it is NOT reachable from `hold`: it
66
+ * is read by `resolveCacheDir` (`src/bundle/cache.ts`), which an agent reaches
67
+ * when its own work runs an owenloop subcommand that touches the bundle cache.
68
+ * It is a directory path, not credential material, and admitting it keeps the
69
+ * worker and anything the agent runs pointed at the same cache.
70
+ *
71
+ * ── THE ONE DENIAL WITH A DELIBERATE CONSEQUENCE ─────────────────────────────
72
+ *
73
+ * `OWENLOOP_TOKEN` is denied, and it IS reachable from `hold`. Left alone that
74
+ * would split the two sides apart: the worker would authenticate to the hub with
75
+ * the override while the child fell back to its credential slot, and an empty
76
+ * slot would surface mid-order as a confusing MCP handshake failure. So
77
+ * `src/roles/agent-run.ts` also ignores `OWENLOOP_TOKEN` when resolving its own
78
+ * bearer. Worker and child then agree, and the failure moves to startup, where
79
+ * `resolveBearer` already refuses with exit code 2 and an actionable message.
80
+ */
81
+ /**
82
+ * The `OWENLOOP_*` names a harness child may see. Everything else in the
83
+ * namespace is removed; everything outside the namespace is untouched.
84
+ *
85
+ * Each entry needs a named consumer that a harness child can actually reach. An
86
+ * entry with no such consumer is a leak with a comment on it.
87
+ */
88
+ export const ADMITTED_OWENLOOP_KEYS = new Set([
89
+ // `resolveCacheDir` — src/bundle/cache.ts. Keeps anything the agent runs on
90
+ // the same bundle cache as the worker. A path, not a secret.
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',
99
+ // `holdShiftId` — src/roles/hold.ts. The fallback when `--shift=` is
100
+ // absent from the mount's argv.
101
+ 'OWENLOOP_SHIFT_ID',
102
+ // `readStoredCredential` — src/hub.ts. Selects the holder's external
103
+ // credential backend rather than falling through to keychain/file defaults.
104
+ 'OWENLOOP_CREDENTIAL_COMMAND',
105
+ // `readStoredCredential` — src/hub.ts. Bounds the external credential helper.
106
+ 'OWENLOOP_CREDENTIAL_COMMAND_TIMEOUT_MS',
107
+ // `readStoredCredential` — src/hub.ts. Forces the 0600 file backend on macOS.
108
+ 'OWENLOOP_NO_KEYCHAIN',
109
+ // `holdSession` — src/roles/hold.ts. The fallback when `--session` is absent.
110
+ 'OWENLOOP_SESSION',
111
+ ]);
112
+ /** The namespace this filter governs. Nothing outside it is ever touched. */
113
+ const NAMESPACE = 'OWENLOOP_';
114
+ /**
115
+ * A copy of `source` with every non-admitted `OWENLOOP_*` key removed.
116
+ *
117
+ * `source` is a parameter rather than a read of `process.env` so callers and
118
+ * tests can inject a fixture; the input is never mutated. Keys are `delete`d
119
+ * rather than set to `undefined`, because an own key holding `undefined` is not
120
+ * obviously equivalent to an absent key once it crosses a spawn or
121
+ * serialization boundary.
122
+ */
123
+ export function filterOwenloopEnv(source) {
124
+ const result = { ...source };
125
+ for (const key of Object.keys(result)) {
126
+ if (key.startsWith(NAMESPACE) && !ADMITTED_OWENLOOP_KEYS.has(key))
127
+ delete result[key];
128
+ }
129
+ return result;
130
+ }
131
+ /** Whether one variable name may reach a harness child. */
132
+ export function isAdmittedChildEnvKey(key) {
133
+ return !key.startsWith(NAMESPACE) || ADMITTED_OWENLOOP_KEYS.has(key);
134
+ }
@@ -0,0 +1,140 @@
1
+ import type { Options, Query, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
+ import type { AgentEvent, HarnessAdapter, HarnessSessionRef, StartArgs, StepPermissions } from './contract.ts';
3
+ /**
4
+ * Build the environment the harness child runs under.
5
+ *
6
+ * WHY IT SPREADS RATHER THAN LISTS. The SDK's `Options.env` REPLACES the
7
+ * subprocess environment entirely — it is NOT merged with `process.env` (see
8
+ * that field's own JSDoc in the installed `sdk.d.ts`). Both halves of that bite:
9
+ *
10
+ * - passing only the deltas would blow away `PATH`/`HOME` and break the child;
11
+ * - omitting `env` altogether would let an ambient API key through, which is
12
+ * exactly the bug this function exists to prevent.
13
+ *
14
+ * So the caller ALWAYS sets `env`, and this function always returns a full
15
+ * environment: spread the source, then delete.
16
+ *
17
+ * `source` is a parameter rather than a read of `process.env` so the unit test
18
+ * injects a fixture and never mutates the real environment. The input is not
19
+ * mutated.
20
+ *
21
+ * `delete` is used rather than assigning `undefined`: an own key holding
22
+ * `undefined` is not obviously equivalent to an absent key across the SDK's
23
+ * serialization boundary, and deleting removes the question.
24
+ *
25
+ * TWO INDEPENDENT FILTERS RUN HERE, and conflating them would break one of
26
+ * them:
27
+ *
28
+ * 1. `STRIPPED_ENV_KEYS` — the vendor API-key strip. It is specific to THIS
29
+ * adapter, it is a correctness requirement (an inherited key shadows the
30
+ * subscription and bills credits), and it is under the `allowApiBilling`
31
+ * opt-out.
32
+ * 2. `filterOwenloopEnv` — Phase 6's `OWENLOOP_*` namespace allowlist, shared
33
+ * with the other adapter and NOT under any opt-out. It removes owenloop's
34
+ * own variables that no harness child has a consumer for — the hub bearer
35
+ * override above all — and touches nothing outside that namespace. In
36
+ * particular it cannot reach `CLAUDE_CODE_OAUTH_TOKEN`, which is not an
37
+ * `OWENLOOP_*` name and therefore survives by construction, which is what
38
+ * Phase 6 item 3 needs under launchd.
39
+ *
40
+ * Everything else survives: `PATH`, `HOME`, `TMPDIR`, proxy and TLS variables,
41
+ * and the three admitted `OWENLOOP_*` names the mounted work-holder MCP child
42
+ * actually reads.
43
+ */
44
+ export declare function buildChildEnv(source: Record<string, string | undefined>, opts: {
45
+ allowApiBilling: boolean;
46
+ }): Record<string, string | undefined>;
47
+ /** Whether API billing is allowed, from a machine-level environment toggle.
48
+ * Default is OFF — the strip happens unless the operator opted in. */
49
+ export declare function allowApiBillingFrom(source: Record<string, string | undefined>): boolean;
50
+ /**
51
+ * Resolve the CLI executable: `OWENLOOP_CLAUDE_BIN` → a `claude` on `PATH` →
52
+ * `undefined`.
53
+ *
54
+ * `undefined` means the caller OMITS `pathToClaudeCodeExecutable` entirely and
55
+ * lets the SDK use its own bundled executable. That third case is a decision,
56
+ * not an oversight: the bundled executable is the same CLI reading the same
57
+ * credential store, so subscription auth still works, whereas throwing would
58
+ * make the adapter unusable on a machine where the CLI sits somewhere unusual.
59
+ *
60
+ * The `PATH` walk is done in-process (`accessSync` with `X_OK`) rather than by
61
+ * shelling out: no shell, no extra child, and it is unit-testable against a
62
+ * fixture `PATH` the test builds and `chmod`s itself.
63
+ *
64
+ * `source` is the CHILD environment (a spread of `process.env`), so the override
65
+ * and the `PATH` searched are the same ones the child will see.
66
+ */
67
+ export declare function resolveExecutable(source: Record<string, string | undefined>): string | undefined;
68
+ /** Everything `buildClaudeOptions` reads for either cold start or resume. */
69
+ export interface ClaudeOptionInputs {
70
+ cwd: string;
71
+ owenloopMcp: {
72
+ command: string;
73
+ args: string[];
74
+ };
75
+ /** Per-start override; wins over `permissions.model`. */
76
+ model?: string;
77
+ /** Per-start override; wins over `permissions.effort`. */
78
+ effort?: string;
79
+ permissions: StepPermissions;
80
+ }
81
+ /** The non-declarative bits a caller supplies per invocation. */
82
+ export interface ClaudeOptionExtras {
83
+ /** The child environment, already built by `buildChildEnv`. Also the source
84
+ * `resolveExecutable` reads the binary override and `PATH` from. */
85
+ env: Record<string, string | undefined>;
86
+ abortController: AbortController;
87
+ onEvent: (e: AgentEvent) => void;
88
+ /** Preselected UUID for a cold start. Never set on a resume. */
89
+ sessionId?: string;
90
+ /** Set on a resume only. Never set on a start. */
91
+ resume?: string;
92
+ }
93
+ /**
94
+ * Map `StartArgs` + the Claude-owned extensions bag onto the SDK's `Options`.
95
+ *
96
+ * The mapping knowledge is PORTED from the legacy compile-time frontmatter
97
+ * builder — the knowledge is correct, only the output format changed. Nothing is
98
+ * imported from `src/adapters/`; the isolation test forbids that dependency
99
+ * direction.
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
+ }
112
+ /** What one consumed turn tells the caller. */
113
+ export interface TurnOutcome {
114
+ /** The session id from the `system/init` message, if one arrived. */
115
+ sessionId: string | undefined;
116
+ /** Whether the turn-end (`result`) message arrived. */
117
+ sawResult: boolean;
118
+ }
119
+ /**
120
+ * Drive the SDK message stream to TURN END and map it onto `AgentEvent`s.
121
+ *
122
+ * Resolves at the `result` message — turn end, per the contract — not at process
123
+ * exit, and regardless of whether the result reports an error.
124
+ *
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.
128
+ *
129
+ * PHASE 6, ITEM 1 — EXPORTED, AND TYPED ON `AsyncIterable` RATHER THAN `Query`.
130
+ * This is the one function that maps the SDK's message stream onto this
131
+ * project's `AgentEvent` contract, so it is the only place a recorded transcript
132
+ * can prove the mapping still matches a shipped vendor build without spawning
133
+ * the vendor binary. `Query` is an `AsyncGenerator` PLUS control methods
134
+ * (`interrupt`, `setModel`, …) that this function never calls; asking only for
135
+ * what it uses is what lets a fixture drive it. A live `Query` still satisfies
136
+ * the narrower type, so nothing at the call sites changes.
137
+ */
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>;
140
+ export declare const claudeAdapter: HarnessAdapter;