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,338 @@
1
+ /**
2
+ * Bundle cache: where `prepare` persists a fetched def and its normalized step
3
+ * specs, keyed by the def CONTENT HASH so a republished def (new hash)
4
+ * invalidates automatically (D2).
5
+ *
6
+ * Layout (D3, as of Phase 5):
7
+ * <cacheDir>/bundles/<workflow-name>/<hash>/
8
+ * bundle.json the validated CachedBundle
9
+ * steps/<step>.json one NormalizedStepSpec per dispatchable agent step
10
+ *
11
+ * There is NO format version and NO migration. A hash dir cached before Phase 5
12
+ * holds `templates/*.md` and no `steps/*.json`, so `readStepSpec` returns null
13
+ * and the caller says so honestly; re-running `owenloop work prepare` is the fix, and
14
+ * content-hash dirs are cheap to re-fetch.
15
+ *
16
+ * Cache-dir resolution order (D3): `OWENLOOP_CACHE_DIR` env → `settings.cacheDir`
17
+ * → `$XDG_CACHE_HOME/owenloop` → `$HOME/.cache/owenloop`; throws when none is
18
+ * available (same stance as settingsPath — never guess a home dir). The env
19
+ * override is primarily how tests point everything at a temp dir.
20
+ *
21
+ * Writes are atomic (temp file + rename) so a concurrent prepare for the same
22
+ * def cannot expose a half-written file — both callers render byte-identical
23
+ * content, so the last rename simply wins (dev's documented concurrency stance).
24
+ *
25
+ * `prepare` is the entry point, NOT fail-open: an unwritable cache dir is a
26
+ * real error the user must see (contrast the GC, which is fail-open). So the
27
+ * write helpers here let fs errors propagate.
28
+ *
29
+ * PINNED-IS-IMMORTAL (E, DD-3 — consumer mirror of hub INV-96): because each
30
+ * hash-pinned child is cached as its own bundle at `bundles/<childName>/<hash>/`
31
+ * and every cached bundle's `def.pins` names the child hashes it froze, the
32
+ * cache itself is the pin index. `pruneSupersededHashes` is pin-aware: a hash
33
+ * pinned by ANY still-cached bundle is never pruned, even when superseded.
34
+ * Lazy cascade (accepted): pruning a superseded PARENT hash removes its pins, so
35
+ * a child hash that thereby becomes unpinned is only reclaimed on the NEXT prune
36
+ * of that child's name, not immediately. All pin scanning is fail-open — a
37
+ * corrupt/unreadable bundle.json is skipped, never fatal.
38
+ */
39
+ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
40
+ import { join } from 'node:path';
41
+ /** Resolve the cache root from env → settings → XDG → HOME. */
42
+ export function resolveCacheDir(env, settingsCacheDir) {
43
+ const override = env['OWENLOOP_CACHE_DIR'];
44
+ if (override !== undefined && override.trim() !== '')
45
+ return override;
46
+ if (settingsCacheDir !== undefined && settingsCacheDir.trim() !== '')
47
+ return settingsCacheDir;
48
+ const xdg = env['XDG_CACHE_HOME'];
49
+ if (xdg !== undefined && xdg.trim() !== '')
50
+ return join(xdg, 'owenloop');
51
+ const home = env['HOME'];
52
+ if (home !== undefined && home.trim() !== '')
53
+ return join(home, '.cache', 'owenloop');
54
+ throw new Error('cannot locate a cache directory: set OWENLOOP_CACHE_DIR, XDG_CACHE_HOME, or HOME');
55
+ }
56
+ /** `<cacheDir>/bundles/<name>` — the dir holding every hash for one workflow. */
57
+ export function workflowDir(cacheDir, name) {
58
+ return join(cacheDir, 'bundles', name);
59
+ }
60
+ /** `<cacheDir>/bundles/<name>/<hash>` — one specific cached def revision. */
61
+ export function hashDir(cacheDir, name, hash) {
62
+ return join(workflowDir(cacheDir, name), hash);
63
+ }
64
+ /**
65
+ * A step name becomes a FILE NAME under `steps/`, so it must not be able to
66
+ * escape the hash dir. Carried over verbatim from the deleted compile layer's
67
+ * `assertSafeStep` — the def is remote input and a step named `../../x` would
68
+ * otherwise write outside the cache.
69
+ */
70
+ function assertSafeStep(step) {
71
+ if (step.includes('/') || step.includes('\\') || step.includes('..')) {
72
+ throw new Error(`unsafe step name '${step}': must not contain '/', '\\', or '..'`);
73
+ }
74
+ }
75
+ /** Atomic write: temp file + rename into place. Fs errors propagate. */
76
+ function atomicWrite(filePath, content) {
77
+ const dir = join(filePath, '..');
78
+ mkdirSync(dir, { recursive: true });
79
+ const tmp = join(dir, `.${Math.random().toString(36).slice(2)}-${process.pid}-${Date.now()}.tmp`);
80
+ writeFileSync(tmp, content);
81
+ try {
82
+ renameSync(tmp, filePath);
83
+ }
84
+ catch (err) {
85
+ try {
86
+ unlinkSync(tmp);
87
+ }
88
+ catch {
89
+ // best-effort cleanup
90
+ }
91
+ throw err;
92
+ }
93
+ }
94
+ /**
95
+ * Write a cached bundle + its normalized step specs under the hash dir. Returns
96
+ * the hash dir path. Overwrites are fine — atomic per file. Each spec lands at
97
+ * `steps/<spec.step>.json`.
98
+ */
99
+ export function writeBundle(cacheDir, bundle, specs) {
100
+ const dir = hashDir(cacheDir, bundle.def.name, bundle.def.hash);
101
+ atomicWrite(join(dir, 'bundle.json'), JSON.stringify(bundle, null, 2) + '\n');
102
+ for (const spec of specs) {
103
+ assertSafeStep(spec.step);
104
+ atomicWrite(join(dir, 'steps', `${spec.step}.json`), JSON.stringify(spec, null, 2) + '\n');
105
+ }
106
+ return dir;
107
+ }
108
+ /**
109
+ * Read a cached bundle for `(name, hash)`, or `null` when absent or corrupt.
110
+ * A corrupt `bundle.json` is treated as absent (refetch), not an error — a
111
+ * cache read must never harden into a failure the user cannot clear by
112
+ * re-fetching.
113
+ */
114
+ export function readBundle(cacheDir, name, hash) {
115
+ const file = join(hashDir(cacheDir, name, hash), 'bundle.json');
116
+ if (!existsSync(file))
117
+ return null;
118
+ try {
119
+ return JSON.parse(readFileSync(file, 'utf8'));
120
+ }
121
+ catch {
122
+ return null;
123
+ }
124
+ }
125
+ /**
126
+ * Read the most-recently-fetched cached bundle for `name`, or `null` when none
127
+ * is cached. After a prepare only one hash dir survives (the others are pruned),
128
+ * but if several exist the newest by `fetchedAt` wins. Corrupt `bundle.json`
129
+ * files are skipped, not fatal.
130
+ */
131
+ export function readLatestBundle(cacheDir, name) {
132
+ const dir = workflowDir(cacheDir, name);
133
+ let hashes;
134
+ try {
135
+ hashes = readdirSync(dir);
136
+ }
137
+ catch {
138
+ return null;
139
+ }
140
+ let best = null;
141
+ for (const hash of hashes) {
142
+ const b = readBundle(cacheDir, name, hash);
143
+ if (b === null)
144
+ continue;
145
+ if (best === null || b.fetchedAt > best.fetchedAt)
146
+ best = b;
147
+ }
148
+ return best;
149
+ }
150
+ class StaleStepSpecError extends Error {
151
+ }
152
+ /**
153
+ * Read the normalized step spec for `(name, hash, step)`, or `null` when it is
154
+ * absent, unreadable, or not valid JSON. Layout mirrors `writeBundle`:
155
+ * `<cacheDir>/bundles/<name>/<hash>/steps/<step>.json`.
156
+ *
157
+ * A missing or corrupt spec returns `null` — a command step has no spec by
158
+ * design, and a hash dir prepared before Phase 5 has none at all. The one
159
+ * deliberate exception is a structurally valid old normalized spec that leaves
160
+ * `filesystem` or `network` buried under `permissions.extensions`: that cache
161
+ * throws with an explicit `owenloop work prepare` repair because returning it
162
+ * would silently discard an authored restriction. There is no fallback to the
163
+ * legacy `templates/<step>.md`.
164
+ */
165
+ export function readStepSpec(cacheDir, name, hash, step) {
166
+ try {
167
+ assertSafeStep(step);
168
+ }
169
+ catch {
170
+ return null;
171
+ }
172
+ const file = join(hashDir(cacheDir, name, hash), 'steps', `${step}.json`);
173
+ if (!existsSync(file))
174
+ return null;
175
+ try {
176
+ const parsed = JSON.parse(readFileSync(file, 'utf8'));
177
+ if (typeof parsed?.step !== 'string' || typeof parsed?.brief !== 'string')
178
+ return null;
179
+ const extensions = parsed.permissions?.extensions;
180
+ if (extensions !== null && typeof extensions === 'object' && !Array.isArray(extensions)) {
181
+ const stale = ['filesystem', 'network'].filter((key) => key in extensions);
182
+ if (stale.length > 0) {
183
+ throw new StaleStepSpecError(`cached step '${step}' has restriction(s) ${stale.join(', ')} buried in permissions.extensions; ` +
184
+ 'rerun `owenloop work prepare`');
185
+ }
186
+ }
187
+ return parsed;
188
+ }
189
+ catch (error) {
190
+ if (error instanceof StaleStepSpecError)
191
+ throw error;
192
+ return null;
193
+ }
194
+ }
195
+ /**
196
+ * Scan every cached bundle's `def.pins` across the whole cache, yielding each
197
+ * pin target as `{name, hash}`. Reads every `bundles/<name>/<hash>/bundle.json`;
198
+ * a corrupt or unreadable bundle.json is skipped (fail-open — a bad file degrades protection
199
+ * toward keeping less, never crashes prepare). Internal: shared by
200
+ * `pruneSupersededHashes`, `collectPinnedHashes`, and `readDispatchBundle`.
201
+ */
202
+ function scanCachedPins(cacheDir) {
203
+ const out = [];
204
+ const bundlesRoot = join(cacheDir, 'bundles');
205
+ let names;
206
+ try {
207
+ names = readdirSync(bundlesRoot);
208
+ }
209
+ catch {
210
+ return out;
211
+ }
212
+ for (const name of names) {
213
+ let hashes;
214
+ try {
215
+ hashes = readdirSync(workflowDir(cacheDir, name));
216
+ }
217
+ catch {
218
+ continue;
219
+ }
220
+ for (const hash of hashes) {
221
+ const b = readBundle(cacheDir, name, hash);
222
+ if (b === null)
223
+ continue; // absent/corrupt → skipped (fail-open)
224
+ for (const pin of b.def.pins ?? []) {
225
+ if (typeof pin?.name === 'string' && typeof pin?.hash === 'string') {
226
+ out.push({ name: pin.name, hash: pin.hash });
227
+ }
228
+ }
229
+ }
230
+ }
231
+ return out;
232
+ }
233
+ /**
234
+ * Every distinct hash of workflow `name` that some still-cached bundle (any
235
+ * name, including a parent, a sibling child, or `name` itself) currently pins.
236
+ * The protected set for pruning and the pin-index for dispatch resolution.
237
+ * Fail-open via `scanCachedPins`.
238
+ */
239
+ export function collectPinnedHashes(cacheDir, name) {
240
+ const set = new Set();
241
+ for (const pin of scanCachedPins(cacheDir)) {
242
+ if (pin.name === name)
243
+ set.add(pin.hash);
244
+ }
245
+ return set;
246
+ }
247
+ /**
248
+ * Delete hash dirs under `<name>` except the protected set (DD-3): `keepHash`
249
+ * plus every hash of `name` pinned by any still-cached bundle (pinned-is-immortal
250
+ * — the consumer mirror of the hub's INV-96). Signature unchanged from D2, so
251
+ * every existing call site inherits the rule. Fail-open: a prune error is
252
+ * swallowed (the fresh bundle is already written; a leftover stale dir is
253
+ * harmless), and a corrupt bundle.json in the pin scan is skipped rather than
254
+ * fatal.
255
+ */
256
+ export function pruneSupersededHashes(cacheDir, name, keepHash) {
257
+ const dir = workflowDir(cacheDir, name);
258
+ const pruned = [];
259
+ let entries;
260
+ try {
261
+ entries = readdirSync(dir);
262
+ }
263
+ catch {
264
+ return pruned;
265
+ }
266
+ const protectedHashes = collectPinnedHashes(cacheDir, name);
267
+ for (const entry of entries) {
268
+ if (entry === keepHash)
269
+ continue;
270
+ if (protectedHashes.has(entry))
271
+ continue; // pinned by some cached bundle → immortal
272
+ try {
273
+ rmSync(join(dir, entry), { recursive: true, force: true });
274
+ pruned.push(entry);
275
+ }
276
+ catch {
277
+ // best-effort per dir
278
+ }
279
+ }
280
+ return pruned;
281
+ }
282
+ /**
283
+ * The dispatch-time bundle selection for `name` (DD-4), used by the shift sweep
284
+ * in place of a bare `readLatestBundle`. `whats_next` serves only the def NAME
285
+ * (no hash, no parent linkage), so per-instance pin disambiguation must come
286
+ * from the local cache's pin index:
287
+ * - 0 pinned hashes for `name` → `readLatestBundle` (today's behavior, byte
288
+ * for byte for the common, unpinned case).
289
+ * - exactly 1 pinned hash h → the bundle AT that hash (single-resolution
290
+ * honored, even when a NEWER unpinned hash of `name` is cached). If that
291
+ * bundle is missing/corrupt we do NOT fall back to latest (that would
292
+ * silently run the wrong version): return `{ bundle: null, warning }` naming
293
+ * `owenloop work prepare <parent>` as the fix — orders lapse via the pickup window.
294
+ * - >1 distinct pinned hashes (two cached parents pin DIFFERENT versions of
295
+ * one child name — legal across parents; the hub only forbids it inside one
296
+ * parent's tree) → ambiguous per-instance, so refuse: `{ bundle: null,
297
+ * warning }`, leave orders for the pickup window. Deliberate fail-safe —
298
+ * never guess a version. Reversible once the hub enriches `whats_next` with a
299
+ * def hash (owenloop-service follow-up, out of scope here).
300
+ */
301
+ export function readDispatchBundle(cacheDir, name) {
302
+ const pinned = collectPinnedHashes(cacheDir, name);
303
+ if (pinned.size === 0) {
304
+ return { bundle: readLatestBundle(cacheDir, name) };
305
+ }
306
+ if (pinned.size > 1) {
307
+ const hashes = [...pinned].sort().join(', ');
308
+ return {
309
+ bundle: null,
310
+ warning: `def '${name}' is pinned to ${pinned.size} distinct hashes (${hashes}) by different cached parents — ` +
311
+ `cannot disambiguate per-instance (whats_next carries no def hash); leaving orders for the pickup window`,
312
+ };
313
+ }
314
+ const [hash] = [...pinned];
315
+ const bundle = readBundle(cacheDir, name, hash);
316
+ if (bundle === null) {
317
+ return {
318
+ bundle: null,
319
+ warning: `def '${name}' is pinned to hash ${hash} but that bundle is not cached — ` +
320
+ `run \`owenloop work prepare\` for the pinning parent; leaving orders for the pickup window`,
321
+ };
322
+ }
323
+ return { bundle };
324
+ }
325
+ /**
326
+ * Resolve the pinned child target for a parent's `calls:` step (pure). Matches
327
+ * `def.pins[].call` against `callStep`, returning `{name, hash}` for the frozen
328
+ * child that step must dispatch, or `null` when the def has no matching pin. The
329
+ * parent-pin → child-bundle resolvable path (item 3 of the brief); D-work builds
330
+ * child-run spawning on top of it.
331
+ */
332
+ export function resolvePinnedChild(def, callStep) {
333
+ for (const pin of def.pins ?? []) {
334
+ if (pin.call === callStep)
335
+ return { name: pin.name, hash: pin.hash };
336
+ }
337
+ return null;
338
+ }
@@ -0,0 +1,87 @@
1
+ import type { FetchedBundle } from './types.ts';
2
+ export interface FetchDefOptions {
3
+ /** Hub origin, e.g. `https://hub.owenloop.dev` (trailing slash tolerated). */
4
+ origin: string;
5
+ /** Workflow name to fetch. */
6
+ name: string;
7
+ /** Resolves the bearer token — the same CredentialReader seam the client uses. */
8
+ getToken: () => Promise<string>;
9
+ /** Override the transport in tests; defaults to the global `fetch`. */
10
+ fetchImpl?: typeof fetch;
11
+ }
12
+ /**
13
+ * The ONE fixed, vendor-neutral sub-key of `x` that carries harness selection
14
+ * and harness options: `x.harness = { id?: string, ...options }`.
15
+ *
16
+ * It is a CONSTANT, not a lookup key derived from a harness name. That is the
17
+ * whole point: `src/agent/loop.ts` used to do `def.x[harnessId]`, which keyed a
18
+ * data structure BY the vendor id and leaked the vendor into neutral code. A
19
+ * fixed key does not.
20
+ */
21
+ export declare const HARNESS_BAG_KEY = "harness";
22
+ /**
23
+ * The sub-key of `x` owenloop used BEFORE `HARNESS_BAG_KEY`. Retained for ONE
24
+ * purpose: so `parseHarnessCarrier` can recognize a def still written to the old
25
+ * grammar and REJECT it loudly. Nothing ever reads what is inside it.
26
+ *
27
+ * ISOLATION NOTE: this is the only harness-vendor-shaped string under `src/`
28
+ * outside the two adapter modules (`src/harness/{claude,codex}.ts`) and the two
29
+ * composition roots' import lines. It is deliberate and it is not a dispatch
30
+ * decision — it names a DEAD key so the parser can tell an author exactly what
31
+ * to rename. Phase 6's repo-wide vendor gate LANDED — `test/vendor-gate.test.ts`
32
+ * — and this file is one of its four allowlist entries, which is the intended
33
+ * outcome. Do NOT "fix" a gate failure here by deleting the check: deleting the
34
+ * check restores the silent, fail-open degradation it exists to prevent.
35
+ */
36
+ export declare const LEGACY_BAG_KEY = "claude-code";
37
+ /** What `parseHarnessCarrier` lifts off one raw step. */
38
+ export interface HarnessCarrier {
39
+ /** The harness id, when the step names one. */
40
+ harness?: string;
41
+ /** Every `x.harness` key except `id`; absent when there are none. */
42
+ harnessOptions?: Record<string, unknown>;
43
+ }
44
+ /**
45
+ * Lift the harness carrier off one RAW step object (D1).
46
+ *
47
+ * Precedence for the id: a TOP-LEVEL `harness` key wins over `x.harness.id`.
48
+ * owenloop's `RAW_STEP_KEYS` rejects unknown top-level step keys at publish
49
+ * today, so a top-level `harness` cannot actually ship yet — reading it is
50
+ * forward compat for the day the grammar promotes the field, and it means the
51
+ * promotion needs no owenloop change.
52
+ *
53
+ * Validation is loose but HONEST: a non-map `x.harness`, a non-string or
54
+ * blank `x.harness.id`, a non-string or blank top-level `harness`, or a
55
+ * surviving legacy `x.claude-code` bag is a def error naming the step, never a
56
+ * silent drop. Absent keys are simply absent — a step with no harness
57
+ * declaration is completely normal. Blank is not absent: accepting an explicit
58
+ * empty id would let adapter resolution treat an invalid declaration as though
59
+ * the author had selected the default harness.
60
+ *
61
+ * `label` names the def, `stepName` the step, so an error in a pinned child is
62
+ * attributable. Shared with `owenloop work lint`, which parses raw YAML defs.
63
+ */
64
+ export declare function parseHarnessCarrier(s: Record<string, unknown>, label: string, stepName: string): HarnessCarrier;
65
+ /**
66
+ * Validate the raw `data` envelope into a `FetchedBundle`. Validates the parent
67
+ * def envelope (hash/steps/coercion/D1 gap), then the OPTIONAL hash-pinned child
68
+ * closure (E). Throws a plain `Error` on any structural problem.
69
+ *
70
+ * Pin/children cross-validation is a HARD fetch error (DD-5) — failing at fetch
71
+ * beats failing mid-run and mirrors the hub's refuse-partial stance:
72
+ * - exactly one of `pins`/`children` present without the other;
73
+ * - a `children` map key that ≠ the entry's own `hash`;
74
+ * - any pin (parent's or a child's) whose `hash` is absent from the flat map
75
+ * (partial closure);
76
+ * - a pin whose `name` ≠ `children[hash].name`.
77
+ * We do NOT re-walk the hub's name-consistency BFS (hub-enforced; duplicating it
78
+ * buys nothing beyond the checks above). Absent both keys → exactly today's
79
+ * shape (no `pins`/`children` materialized on the return).
80
+ */
81
+ export declare function validateFetchedDef(data: unknown, name: string): FetchedBundle;
82
+ /**
83
+ * Fetch and validate a workflow def. Non-2xx becomes a `HubError` (status +
84
+ * message, mirroring the hub client's parse); a 2xx body that is not the
85
+ * enriched shape becomes a plain `Error` from `validateFetchedDef`.
86
+ */
87
+ export declare function fetchDef(opts: FetchDefOptions): Promise<FetchedBundle>;