owenloop 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -0,0 +1,324 @@
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
+ /**
151
+ * Read the normalized step spec for `(name, hash, step)`, or `null` when it is
152
+ * absent, unreadable, or not valid JSON. Layout mirrors `writeBundle`:
153
+ * `<cacheDir>/bundles/<name>/<hash>/steps/<step>.json`.
154
+ *
155
+ * Never throws — a missing spec is a normal case the caller reports and moves
156
+ * past (a command step has no spec by design, and a hash dir prepared before
157
+ * Phase 5 has none at all). There is deliberately NO fallback to the legacy
158
+ * `templates/<step>.md`: silently running a stale compiled template would be
159
+ * worse than an honest "re-run `owenloop work prepare`".
160
+ */
161
+ export function readStepSpec(cacheDir, name, hash, step) {
162
+ try {
163
+ assertSafeStep(step);
164
+ }
165
+ catch {
166
+ return null;
167
+ }
168
+ const file = join(hashDir(cacheDir, name, hash), 'steps', `${step}.json`);
169
+ if (!existsSync(file))
170
+ return null;
171
+ try {
172
+ const parsed = JSON.parse(readFileSync(file, 'utf8'));
173
+ if (typeof parsed?.step !== 'string' || typeof parsed?.brief !== 'string')
174
+ return null;
175
+ return parsed;
176
+ }
177
+ catch {
178
+ return null;
179
+ }
180
+ }
181
+ /**
182
+ * Scan every cached bundle's `def.pins` across the whole cache, yielding each
183
+ * pin target as `{name, hash}`. Reads every `bundles/<name>/<hash>/bundle.json`;
184
+ * a corrupt or unreadable bundle.json is skipped (fail-open — a bad file degrades protection
185
+ * toward keeping less, never crashes prepare). Internal: shared by
186
+ * `pruneSupersededHashes`, `collectPinnedHashes`, and `readDispatchBundle`.
187
+ */
188
+ function scanCachedPins(cacheDir) {
189
+ const out = [];
190
+ const bundlesRoot = join(cacheDir, 'bundles');
191
+ let names;
192
+ try {
193
+ names = readdirSync(bundlesRoot);
194
+ }
195
+ catch {
196
+ return out;
197
+ }
198
+ for (const name of names) {
199
+ let hashes;
200
+ try {
201
+ hashes = readdirSync(workflowDir(cacheDir, name));
202
+ }
203
+ catch {
204
+ continue;
205
+ }
206
+ for (const hash of hashes) {
207
+ const b = readBundle(cacheDir, name, hash);
208
+ if (b === null)
209
+ continue; // absent/corrupt → skipped (fail-open)
210
+ for (const pin of b.def.pins ?? []) {
211
+ if (typeof pin?.name === 'string' && typeof pin?.hash === 'string') {
212
+ out.push({ name: pin.name, hash: pin.hash });
213
+ }
214
+ }
215
+ }
216
+ }
217
+ return out;
218
+ }
219
+ /**
220
+ * Every distinct hash of workflow `name` that some still-cached bundle (any
221
+ * name, including a parent, a sibling child, or `name` itself) currently pins.
222
+ * The protected set for pruning and the pin-index for dispatch resolution.
223
+ * Fail-open via `scanCachedPins`.
224
+ */
225
+ export function collectPinnedHashes(cacheDir, name) {
226
+ const set = new Set();
227
+ for (const pin of scanCachedPins(cacheDir)) {
228
+ if (pin.name === name)
229
+ set.add(pin.hash);
230
+ }
231
+ return set;
232
+ }
233
+ /**
234
+ * Delete hash dirs under `<name>` except the protected set (DD-3): `keepHash`
235
+ * plus every hash of `name` pinned by any still-cached bundle (pinned-is-immortal
236
+ * — the consumer mirror of the hub's INV-96). Signature unchanged from D2, so
237
+ * every existing call site inherits the rule. Fail-open: a prune error is
238
+ * swallowed (the fresh bundle is already written; a leftover stale dir is
239
+ * harmless), and a corrupt bundle.json in the pin scan is skipped rather than
240
+ * fatal.
241
+ */
242
+ export function pruneSupersededHashes(cacheDir, name, keepHash) {
243
+ const dir = workflowDir(cacheDir, name);
244
+ const pruned = [];
245
+ let entries;
246
+ try {
247
+ entries = readdirSync(dir);
248
+ }
249
+ catch {
250
+ return pruned;
251
+ }
252
+ const protectedHashes = collectPinnedHashes(cacheDir, name);
253
+ for (const entry of entries) {
254
+ if (entry === keepHash)
255
+ continue;
256
+ if (protectedHashes.has(entry))
257
+ continue; // pinned by some cached bundle → immortal
258
+ try {
259
+ rmSync(join(dir, entry), { recursive: true, force: true });
260
+ pruned.push(entry);
261
+ }
262
+ catch {
263
+ // best-effort per dir
264
+ }
265
+ }
266
+ return pruned;
267
+ }
268
+ /**
269
+ * The dispatch-time bundle selection for `name` (DD-4), used by the shift sweep
270
+ * in place of a bare `readLatestBundle`. `whats_next` serves only the def NAME
271
+ * (no hash, no parent linkage), so per-instance pin disambiguation must come
272
+ * from the local cache's pin index:
273
+ * - 0 pinned hashes for `name` → `readLatestBundle` (today's behavior, byte
274
+ * for byte for the common, unpinned case).
275
+ * - exactly 1 pinned hash h → the bundle AT that hash (single-resolution
276
+ * honored, even when a NEWER unpinned hash of `name` is cached). If that
277
+ * bundle is missing/corrupt we do NOT fall back to latest (that would
278
+ * silently run the wrong version): return `{ bundle: null, warning }` naming
279
+ * `owenloop work prepare <parent>` as the fix — orders lapse via the pickup window.
280
+ * - >1 distinct pinned hashes (two cached parents pin DIFFERENT versions of
281
+ * one child name — legal across parents; the hub only forbids it inside one
282
+ * parent's tree) → ambiguous per-instance, so refuse: `{ bundle: null,
283
+ * warning }`, leave orders for the pickup window. Deliberate fail-safe —
284
+ * never guess a version. Reversible once the hub enriches `whats_next` with a
285
+ * def hash (owenloop-service follow-up, out of scope here).
286
+ */
287
+ export function readDispatchBundle(cacheDir, name) {
288
+ const pinned = collectPinnedHashes(cacheDir, name);
289
+ if (pinned.size === 0) {
290
+ return { bundle: readLatestBundle(cacheDir, name) };
291
+ }
292
+ if (pinned.size > 1) {
293
+ const hashes = [...pinned].sort().join(', ');
294
+ return {
295
+ bundle: null,
296
+ warning: `def '${name}' is pinned to ${pinned.size} distinct hashes (${hashes}) by different cached parents — ` +
297
+ `cannot disambiguate per-instance (whats_next carries no def hash); leaving orders for the pickup window`,
298
+ };
299
+ }
300
+ const [hash] = [...pinned];
301
+ const bundle = readBundle(cacheDir, name, hash);
302
+ if (bundle === null) {
303
+ return {
304
+ bundle: null,
305
+ warning: `def '${name}' is pinned to hash ${hash} but that bundle is not cached — ` +
306
+ `run \`owenloop work prepare\` for the pinning parent; leaving orders for the pickup window`,
307
+ };
308
+ }
309
+ return { bundle };
310
+ }
311
+ /**
312
+ * Resolve the pinned child target for a parent's `calls:` step (pure). Matches
313
+ * `def.pins[].call` against `callStep`, returning `{name, hash}` for the frozen
314
+ * child that step must dispatch, or `null` when the def has no matching pin. The
315
+ * parent-pin → child-bundle resolvable path (item 3 of the brief); D-work builds
316
+ * child-run spawning on top of it.
317
+ */
318
+ export function resolvePinnedChild(def, callStep) {
319
+ for (const pin of def.pins ?? []) {
320
+ if (pin.call === callStep)
321
+ return { name: pin.name, hash: pin.hash };
322
+ }
323
+ return null;
324
+ }
@@ -0,0 +1,85 @@
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
54
+ * `x.harness.id`, a non-string top-level `harness`, or a surviving legacy
55
+ * `x.claude-code` bag is a def error naming the step, never a silent drop.
56
+ * Absent keys are simply absent — a step with no harness declaration is
57
+ * completely normal.
58
+ *
59
+ * `label` names the def, `stepName` the step, so an error in a pinned child is
60
+ * attributable. Shared with `owenloop work lint`, which parses raw YAML defs.
61
+ */
62
+ export declare function parseHarnessCarrier(s: Record<string, unknown>, label: string, stepName: string): HarnessCarrier;
63
+ /**
64
+ * Validate the raw `data` envelope into a `FetchedBundle`. Validates the parent
65
+ * def envelope (hash/steps/coercion/D1 gap), then the OPTIONAL hash-pinned child
66
+ * closure (E). Throws a plain `Error` on any structural problem.
67
+ *
68
+ * Pin/children cross-validation is a HARD fetch error (DD-5) — failing at fetch
69
+ * beats failing mid-run and mirrors the hub's refuse-partial stance:
70
+ * - exactly one of `pins`/`children` present without the other;
71
+ * - a `children` map key that ≠ the entry's own `hash`;
72
+ * - any pin (parent's or a child's) whose `hash` is absent from the flat map
73
+ * (partial closure);
74
+ * - a pin whose `name` ≠ `children[hash].name`.
75
+ * We do NOT re-walk the hub's name-consistency BFS (hub-enforced; duplicating it
76
+ * buys nothing beyond the checks above). Absent both keys → exactly today's
77
+ * shape (no `pins`/`children` materialized on the return).
78
+ */
79
+ export declare function validateFetchedDef(data: unknown, name: string): FetchedBundle;
80
+ /**
81
+ * Fetch and validate a workflow def. Non-2xx becomes a `HubError` (status +
82
+ * message, mirroring the hub client's parse); a 2xx body that is not the
83
+ * enriched shape becomes a plain `Error` from `validateFetchedDef`.
84
+ */
85
+ export declare function fetchDef(opts: FetchDefOptions): Promise<FetchedBundle>;