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,109 @@
1
+ export { resolveOwenloopBin } from '../owenloop-bin.ts';
2
+ /**
3
+ * What to spawn: the order to run. `run` IS the order id (hub verb contract);
4
+ * `workflow` pairs with it (every hub verb needs both). The hub `origin` is NOT
5
+ * here — it is captured by `createDefaultSpawner` (one hub per shift), so the
6
+ * loop, which knows only the order, calls the seam without carrying it.
7
+ */
8
+ export interface SpawnSpec {
9
+ workflow: string;
10
+ run: string;
11
+ /** Step name, carried only for safe local lifecycle reporting. */
12
+ step?: string;
13
+ /**
14
+ * Which role the detached child runs (Phase 3). Absent ⇒ `'exec'`, so every
15
+ * pre-Phase-3 caller and every faked spawner in the existing tests keeps its
16
+ * exact meaning.
17
+ *
18
+ * - `'exec'` — a COMMAND order; the child runs `owenloop work exec`.
19
+ * - `'agent-run'` — an AGENT order; the child runs `owenloop work agent-run` and
20
+ * hosts the step agent itself. This is the ONLY agent path.
21
+ */
22
+ kind?: 'exec' | 'agent-run';
23
+ /**
24
+ * Optional safe lifecycle-reporting label for an `agent-run` child. This field
25
+ * never becomes `--harness`; the child resolves the authoritative harness from
26
+ * CLI/environment/verified runtime definition precedence.
27
+ */
28
+ harness?: string;
29
+ /** Closed start gate created by the durable Shift reservation. */
30
+ startGate?: string;
31
+ }
32
+ /** The result the loop records plus best-effort pre-start cancellation handles. */
33
+ export interface SpawnResult {
34
+ pid: number;
35
+ /**
36
+ * Dispatcher-owned cancellation. The default spawner disarms spontaneous
37
+ * lifecycle reporting before sending SIGTERM, so one failed dispatch emits
38
+ * one Shift failure event.
39
+ */
40
+ cancel?: () => void;
41
+ /** Legacy injected-spawner compatibility. New dispatcher code prefers cancel. */
42
+ terminate?: () => void;
43
+ }
44
+ /** The spawn seam. Injected; faked in tests. */
45
+ export type Spawner = (spec: SpawnSpec) => SpawnResult;
46
+ /** Safe, bounded metadata emitted when a detached worker fails. Detached
47
+ * worker stderr is not attached to Shift: agent-run output is untrusted, and a
48
+ * parent-owned pipe can kill either worker with EPIPE after Shift exits. */
49
+ export interface WorkerFailure {
50
+ workflow: string;
51
+ run: string;
52
+ step?: string;
53
+ kind: 'exec' | 'agent-run';
54
+ harness?: string;
55
+ executable: string;
56
+ exitStatus: number | null;
57
+ signal: NodeJS.Signals | null;
58
+ message: string;
59
+ }
60
+ export type WorkerFailureReporter = (failure: WorkerFailure) => void;
61
+ /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
62
+ export interface SpawnPlan {
63
+ command: string;
64
+ args: string[];
65
+ options: {
66
+ detached: true;
67
+ stdio: ['ignore', 'ignore', 'ignore'];
68
+ env: NodeJS.ProcessEnv;
69
+ };
70
+ }
71
+ /**
72
+ * Build the argv + options for a detached
73
+ * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
74
+ * tests assert the shape without launching anything. Runs the bin under the
75
+ * current Node (`execPath`), matching the `owenloop work exec <order-id>` arg contract
76
+ * (the composite `<workflow>/<run>` carries both ids in one positional).
77
+ *
78
+ * The account is NOT an argv flag — it rides `options.env.OWENLOOP_ACCOUNT`.
79
+ * `env` starts from `process.env` so the detached child keeps the parent's
80
+ * environment inheritance (which is otherwise implicit when `env` is unset),
81
+ * then sets the resolved account on top.
82
+ *
83
+ * `shiftId` (W7, trailing — after `execPath` so existing positional
84
+ * callers are unaffected), when non-empty, appends `--shift <cid>` so the
85
+ * spawned `owenloop work exec` child self-declares which Shift dispatched it
86
+ * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
87
+ *
88
+ * Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
89
+ * selects the role positional (`exec` vs `agent-run`). Everything else — the
90
+ * composite order positional, `--origin`, `--shift`, and every spawn option
91
+ * — is identical for both kinds, so an agent-run child is detached,
92
+ * stdio-ignored, and account-scoped exactly like an exec child.
93
+ *
94
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
95
+ * not an operator override; the `agent-run` child resolves its authoritative
96
+ * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
97
+ * step, registered default). The Shift command has no operator-facing harness
98
+ * flag, so there is no legitimate CLI override for this seam to carry.
99
+ */
100
+ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string): SpawnPlan;
101
+ /**
102
+ * The default detached spawner. Captures the resolved hub `origin`, the
103
+ * resolved `account`, the packaged bin path, and the dispatching Shift's
104
+ * `shiftId` once at construction; each spawn threads them into the
105
+ * child's argv + spawn env. `execPath` is passed explicitly (rather than
106
+ * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
107
+ * — can be supplied positionally.
108
+ */
109
+ export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter): Spawner;
@@ -0,0 +1,158 @@
1
+ /**
2
+ * The detached-exec spawn seam (plan decision 6).
3
+ *
4
+ * Every order the shift dispatches becomes a DETACHED
5
+ * `owenloop work exec <workflow>/<run> --origin <url>` child: `detached: true`,
6
+ * all stdio ignored, `unref()` — so the child is its own process-group leader and
7
+ * survives the parent's death (SP5-verified kernel reparenting). The shift meters
8
+ * and hands off; the child self-leases (C5). Both ids ride the argv as the
9
+ * composite `<workflow>/<run>` order-id `owenloop work exec` parses, and `--origin`
10
+ * is passed through so the detached child reaches the SAME hub the shift is
11
+ * parked at without re-reading settings. The shift-resolved account rides the
12
+ * child's spawn ENV as `OWENLOOP_ACCOUNT` (exec has no `--as` flag — the spawn
13
+ * env is the contract), selecting which Scoped Identity credential slot
14
+ * (agent:<account>) exec reads.
15
+ *
16
+ * `Spawner` is an injected seam; most loop tests fake it. The default impl's
17
+ * argv/option construction is factored into the pure `buildSpawnPlan`, while a
18
+ * focused lifecycle regression uses harmless local children.
19
+ */
20
+ import { spawn } from 'node:child_process';
21
+ import { resolveOwenloopBin } from "../owenloop-bin.js";
22
+ export { resolveOwenloopBin } from "../owenloop-bin.js";
23
+ /**
24
+ * Build the argv + options for a detached
25
+ * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
26
+ * tests assert the shape without launching anything. Runs the bin under the
27
+ * current Node (`execPath`), matching the `owenloop work exec <order-id>` arg contract
28
+ * (the composite `<workflow>/<run>` carries both ids in one positional).
29
+ *
30
+ * The account is NOT an argv flag — it rides `options.env.OWENLOOP_ACCOUNT`.
31
+ * `env` starts from `process.env` so the detached child keeps the parent's
32
+ * environment inheritance (which is otherwise implicit when `env` is unset),
33
+ * then sets the resolved account on top.
34
+ *
35
+ * `shiftId` (W7, trailing — after `execPath` so existing positional
36
+ * callers are unaffected), when non-empty, appends `--shift <cid>` so the
37
+ * spawned `owenloop work exec` child self-declares which Shift dispatched it
38
+ * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
39
+ *
40
+ * Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
41
+ * selects the role positional (`exec` vs `agent-run`). Everything else — the
42
+ * composite order positional, `--origin`, `--shift`, and every spawn option
43
+ * — is identical for both kinds, so an agent-run child is detached,
44
+ * stdio-ignored, and account-scoped exactly like an exec child.
45
+ *
46
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
47
+ * not an operator override; the `agent-run` child resolves its authoritative
48
+ * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
49
+ * step, registered default). The Shift command has no operator-facing harness
50
+ * flag, so there is no legitimate CLI override for this seam to carry.
51
+ */
52
+ export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId) {
53
+ const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
54
+ return {
55
+ command: execPath,
56
+ args: [
57
+ binPath,
58
+ 'work',
59
+ role,
60
+ `${spec.workflow}/${spec.run}`,
61
+ '--origin',
62
+ origin,
63
+ ...(shiftId !== undefined && shiftId !== '' ? ['--shift', shiftId] : []),
64
+ ],
65
+ options: {
66
+ detached: true,
67
+ stdio: ['ignore', 'ignore', 'ignore'],
68
+ env: {
69
+ ...process.env,
70
+ OWENLOOP_ACCOUNT: account,
71
+ ...(spec.startGate !== undefined ? { OWENLOOP_START_GATE: spec.startGate } : {}),
72
+ },
73
+ },
74
+ };
75
+ }
76
+ /**
77
+ * The default detached spawner. Captures the resolved hub `origin`, the
78
+ * resolved `account`, the packaged bin path, and the dispatching Shift's
79
+ * `shiftId` once at construction; each spawn threads them into the
80
+ * child's argv + spawn env. `execPath` is passed explicitly (rather than
81
+ * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
82
+ * — can be supplied positionally.
83
+ */
84
+ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure) {
85
+ return (spec) => {
86
+ const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId);
87
+ const child = spawn(plan.command, plan.args, plan.options);
88
+ const kind = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
89
+ const harness = kind === 'agent-run'
90
+ ? (spec.harness ?? process.env['OWENLOOP_HARNESS'] ?? 'auto')
91
+ : undefined;
92
+ // This process is the executable Shift actually launched. The harness may
93
+ // start its own vendor process later, but reporting or guessing that
94
+ // executable here would couple the neutral dispatcher to one adapter.
95
+ const executable = `${process.execPath} ${binPath}`;
96
+ // No worker stdio slot is a parent-owned pipe. Once Shift exits, a detached
97
+ // worker may keep writing diagnostics without receiving EPIPE from a vanished
98
+ // reader. Agent-run stderr is untrusted; exec failures therefore use the same
99
+ // bounded generic lifecycle message rather than capturing worker output.
100
+ let failureReported = false;
101
+ const report = (exitStatus, signal, message) => {
102
+ if (failureReported || onFailure === undefined)
103
+ return;
104
+ failureReported = true;
105
+ onFailure({
106
+ workflow: spec.workflow,
107
+ run: spec.run,
108
+ ...(spec.step !== undefined ? { step: spec.step } : {}),
109
+ kind,
110
+ ...(harness !== undefined ? { harness } : {}),
111
+ executable,
112
+ exitStatus,
113
+ signal,
114
+ message,
115
+ });
116
+ };
117
+ child.once('error', () => report(null, null, 'worker process failed to start'));
118
+ child.once('exit', (code, signal) => {
119
+ if (code === 0)
120
+ return;
121
+ report(code, signal, 'worker exited without completing successfully');
122
+ });
123
+ child.unref();
124
+ if (child.pid === undefined) {
125
+ // A synchronous spawn failure leaves no pid AND makes Node emit `error` on
126
+ // a later tick (verified on node v22: `pid` undefined, events `error` then
127
+ // `close`, no `exit`). The spawned COMMAND here is always
128
+ // `process.execPath`, never `binPath`, so the trigger is not a missing bin
129
+ // — it is resource exhaustion in the Shift itself (EMFILE from too many
130
+ // concurrent children, ENOMEM), which is exactly the condition a busy
131
+ // dispatcher hits. Throwing is what the caller sees, and
132
+ // `createShiftLoop.dispatchCandidate` already turns that throw into one
133
+ // `failed` event. Latch the reporter closed first, or the `error` handler
134
+ // registered above fires afterwards and emits a SECOND `failed` event —
135
+ // two daemon events for one dispatch attempt.
136
+ failureReported = true;
137
+ throw new Error(`spawn of 'owenloop work ${kind} ${spec.workflow}/${spec.run}' returned no pid`);
138
+ }
139
+ const kill = () => {
140
+ try {
141
+ child.kill('SIGTERM');
142
+ }
143
+ catch {
144
+ // The child may already have exited after a cancelled or missing gate.
145
+ }
146
+ };
147
+ return {
148
+ pid: child.pid,
149
+ cancel: () => {
150
+ // Dispatcher-owned termination has its own authoritative failure event.
151
+ // Latch first so the resulting signal exit cannot report a second event.
152
+ failureReported = true;
153
+ kill();
154
+ },
155
+ terminate: kill,
156
+ };
157
+ };
158
+ }
@@ -0,0 +1,79 @@
1
+ export declare const DEFAULT_RESERVATION_MAX_AGE_MS: number;
2
+ export interface ChildRecord {
3
+ workflow: string;
4
+ run: string;
5
+ pid: number;
6
+ spawnedAt: number;
7
+ /** Dispatch kind; absent = `'exec'` for backward compatibility. */
8
+ kind?: 'exec' | 'agent-run';
9
+ def?: string;
10
+ hash?: string;
11
+ step?: string;
12
+ /** Present only between PID persistence and opening the child's start gate. */
13
+ gateToken?: string;
14
+ }
15
+ export interface ChildReservation {
16
+ recordType: 'reservation';
17
+ workflow: string;
18
+ run: string;
19
+ reservedAt: number;
20
+ token: string;
21
+ childKind: 'exec' | 'agent-run';
22
+ step?: string;
23
+ }
24
+ export interface ReservationRequest {
25
+ workflow: string;
26
+ run: string;
27
+ reservedAt: number;
28
+ childKind: 'exec' | 'agent-run';
29
+ step?: string;
30
+ }
31
+ export interface ReservedChild {
32
+ reservation: ChildReservation;
33
+ gatePath: string;
34
+ }
35
+ export declare function resolveStateDir(env: Record<string, string | undefined>, override?: string): string;
36
+ /** Persist a child record atomically. State persistence is correctness-sensitive and throws on failure. */
37
+ export declare function writeChildRecord(stateDir: string, record: ChildRecord): void;
38
+ /** Create the durable capacity reservation and closed start gate before spawn. */
39
+ export declare function reserveChild(stateDir: string, request: ReservationRequest): ReservedChild;
40
+ export declare class ShiftStateRecordError extends Error {
41
+ readonly path: string;
42
+ constructor(path: string, detail: string);
43
+ }
44
+ /** Read only PID-bearing records for status and compatibility callers. */
45
+ export declare function readChildRecords(stateDir: string): ChildRecord[];
46
+ export declare function readChildReservations(stateDir: string): ChildReservation[];
47
+ /** Replace the matching reservation with a PID-bearing record before work starts. */
48
+ export declare function finalizeChildReservation(stateDir: string, reservation: ChildReservation, child: Omit<ChildRecord, 'workflow' | 'run' | 'gateToken'>): ChildRecord;
49
+ /** Open a child's gate only after the PID-bearing record is durable. */
50
+ export declare function startReservedChild(stateDir: string, record: ChildRecord): void;
51
+ /** Cancel a gated child and remove the matching reservation/record. */
52
+ export declare function cancelReservedChild(stateDir: string, reservation: ChildReservation): void;
53
+ /**
54
+ * Delete one run's in-flight state. A still-gated reservation or finalized child
55
+ * is cancelled first so an external run-ended signal cannot leave a worker gate
56
+ * behind that later opens without a capacity record.
57
+ */
58
+ export declare function removeChildRecord(stateDir: string, run: string): void;
59
+ export type Liveness = (pid: number) => boolean;
60
+ export declare const defaultIsAlive: Liveness;
61
+ export interface Reconciliation {
62
+ live: ChildRecord[];
63
+ reserved: ChildReservation[];
64
+ reaped: ChildRecord[];
65
+ abandoned: ChildReservation[];
66
+ }
67
+ export interface ReconcileOptions {
68
+ isAlive?: Liveness;
69
+ now?: number;
70
+ reservationMaxAgeMs?: number;
71
+ }
72
+ /**
73
+ * Reconcile live children and durable reservations. Fresh reservations count as
74
+ * occupied capacity. An expired reservation is cancelled before its record is
75
+ * removed, so a child that was spawned but never finalized cannot begin work.
76
+ */
77
+ export declare function reconcileInFlight(stateDir: string, arg?: Liveness | ReconcileOptions): Reconciliation;
78
+ /** Ensure the state directory exists and is readable. Failure is fatal to dispatch safety. */
79
+ export declare function ensureStateDir(stateDir: string): void;