owenloop 0.4.1 → 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 (154) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +58 -31
  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/{cli.d.ts → src/cli.d.ts} +18 -3
  109. package/dist/{cli.js → src/cli.js} +770 -114
  110. package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
  111. package/dist/{credentials.js → src/credentials.js} +14 -12
  112. package/dist/{defs.js → src/defs.js} +36 -36
  113. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  114. package/dist/{engine.js → src/engine.js} +14 -14
  115. package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
  116. package/dist/{hub.js → src/hub.js} +370 -12
  117. package/dist/{index.d.ts → src/index.d.ts} +1 -1
  118. package/dist/{index.js → src/index.js} +1 -1
  119. package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
  120. package/dist/{mcp → src/mcp}/serve.js +168 -31
  121. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  122. package/dist/{mcp → src/mcp}/server.js +6 -9
  123. package/dist/{model.js → src/model.js} +1 -1
  124. package/dist/{types.d.ts → src/types.d.ts} +18 -18
  125. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  126. package/dist/{util.js → src/util.js} +3 -2
  127. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  128. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  129. package/docs/authoring.md +93 -53
  130. package/docs/cli.md +597 -76
  131. package/docs/design.md +33 -33
  132. package/docs/embedding.md +10 -9
  133. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  134. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  135. package/examples/workflows/judges/gate-sharpness.md +39 -0
  136. package/examples/workflows/judges/security.md +34 -0
  137. package/package.json +17 -8
  138. /package/dist/{add.d.ts → src/add.d.ts} +0 -0
  139. /package/dist/{add.js → src/add.js} +0 -0
  140. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  141. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  142. /package/dist/{factory.js → src/factory.js} +0 -0
  143. /package/dist/{lock.d.ts → src/lock.d.ts} +0 -0
  144. /package/dist/{lock.js → src/lock.js} +0 -0
  145. /package/dist/{model.d.ts → src/model.d.ts} +0 -0
  146. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  147. /package/dist/{paths.js → src/paths.js} +0 -0
  148. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  149. /package/dist/{schema.js → src/schema.js} +0 -0
  150. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  151. /package/dist/{store.js → src/store.js} +0 -0
  152. /package/dist/{types.js → src/types.js} +0 -0
  153. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  154. /package/dist/{untar.js → src/untar.js} +0 -0
package/docs/design.md CHANGED
@@ -663,7 +663,7 @@ The `M2B-REARM` branch (§23.6.1 step 7 — child un-greened while parent stays
663
663
  - **Aggregation.** Child orders are concatenated onto the parent's; `reaped` sums; `dueAt` takes the minimum across the tree so the caller's next-wake is the earliest across all levels. Each folded `DeferredFiring` carries a `workflow` field naming the instance it belongs to — **absent means the ticked root, present means a descendant** — so a caller can still tell which instance a deferral came from. The single `now` is threaded through the whole descent, so a reap TTL that trips at the parent's clock trips consistently for children in the same sweep.
664
664
  - **Opt-out.** `tick(parentWf, { deep: false })` (CLI `--shallow`) ticks only that one instance — no descent, orders all carry the root's `workflow`. Use it to drive a single instance deliberately (tests, targeted retries); the default deep tick is what production drivers want.
665
665
 
666
- **Status child-summary.** `status(parentWf)` enriches each `calls:`-debt entry with a `child: ChildStatusSummary` (`{ workflow, def, done, stalled, debts }`) when a child has been spawned for that step. `stalled` is true when the child (or, recursively, a grandchild on an unpaid `calls:` path) has any stalled debt — a worker that hit `maxAttempts` with no green outcome. This lets a conductor see, from the parent alone, that a `calls:` debt is blocked on a stuck child without separately walking into the child's own `status`. Like `failedRuns`/`attempts`, the field is engine-populated cross-instance state; `model.ts`'s pure single-instance `workflowStatus` never sets it.
666
+ **Status child-summary.** `status(parentWf)` enriches each `calls:`-debt entry with a `child: ChildStatusSummary` (`{ workflow, def, done, stalled, debts }`) when a child has been spawned for that step. `stalled` is true when the child (or, recursively, a grandchild on an unpaid `calls:` path) has any stalled debt — a worker that hit `maxAttempts` with no green outcome. This lets a Shift see, from the parent alone, that a `calls:` debt is blocked on a stuck child without separately walking into the child's own `status`. Like `failedRuns`/`attempts`, the field is engine-populated cross-instance state; `model.ts`'s pure single-instance `workflowStatus` never sets it.
667
667
 
668
668
  **Discovering children directly.** A driver can still enumerate children itself — `store.listChildrenByParent`/`findChildByParent` give the reverse index from a parent id — and a propagated reject remains visible via the CHILD's own `status(childWf).debts` (the rejected outcome artifact appears there with `acceptance: 'rejected'`). But with deep tick as the default, a driver that sweeps only roots already reaches all live descendants; explicit child enumeration is for inspection and for the `--shallow` single-instance path, not a requirement for liveness.
669
669
 
@@ -875,7 +875,7 @@ steps:
875
875
  ```
876
876
 
877
877
  - `name:` — required; keys the sign-off ledger and the audit trail.
878
- - `body:` / `bodyFile:` — the judge agent's prompt (exactly one required,
878
+ - `body:` / `bodyFile:` — the judge Step Agent's prompt (exactly one required,
879
879
  mutually exclusive, same rule as step bodies). `bodyFile` is resolved
880
880
  against the workflow's base directory and read eagerly at def-load.
881
881
  - `model:` — optional model override for that judge's order. Opaque to the
@@ -919,12 +919,12 @@ left as a known, accepted limitation — see the doc comment on `reject()` in
919
919
  `src/engine.ts`.
920
920
 
921
921
  **Mitigations, for operators running judges with slow or expensive verdict
922
- agents:**
922
+ Step Agents:**
923
923
 
924
924
  - Keep `judges: <judgedStem>` steps at `parallel: 1` (the default) so there
925
925
  is only ever one live run of a given judge step at a time. This alone
926
926
  removes the "two different runs" precondition for the race.
927
- - Set a generous `reapTtl:` on judge steps whose verdict agent is slow —
927
+ - Set a generous `reapTtl:` on judge steps whose verdict Step Agent is slow —
928
928
  reaping is what creates the zombie in the first place (§24.5); a judge
929
929
  that is legitimately still working should not be reaped out from under
930
930
  itself. A TTL sized to the judge's real worst-case latency, rather than
@@ -1317,39 +1317,39 @@ prefixing untouched (there are no stems inside `x:` to rewrite — it's
1317
1317
  opaque); a child definition's own top-level `x:` stays on the child def and
1318
1318
  is not merged into the parent's.
1319
1319
 
1320
- ### §27.4 `worker:`/`command:`/`spec:` — declaring the executor
1320
+ ### §27.4 `executor:`/`command:`/`spec:` — declaring the executor
1321
1321
 
1322
1322
  `x:` (§27.3) is a namespaced escape hatch for arbitrary external vocabulary.
1323
- `worker:` is a narrower, purpose-built field for one specific job: telling
1323
+ `executor:` is a narrower, purpose-built field for one specific job: telling
1324
1324
  whatever dispatches orders *which kind* of executor a step's order is for. It
1325
1325
  follows the same opaque-passthrough contract as `model` — the engine never
1326
1326
  interprets it, only carries it — but unlike `model` (a free-form quality
1327
- hint) and unlike `x:` (fully unvalidated contents), `worker:` gets two narrow,
1328
- hard-coded shape rules, because the two most common worker types have a
1327
+ hint) and unlike `x:` (fully unvalidated contents), `executor:` gets two narrow,
1328
+ hard-coded shape rules, because the two most common executor types have a
1329
1329
  structural precondition the engine can cheaply catch at load time instead of
1330
1330
  letting it surface as a confusing runtime stall.
1331
1331
 
1332
1332
  **The contract, four clauses:**
1333
1333
 
1334
1334
  1. **Default is `'agent'`, and that default is silent.** A step (or judge)
1335
- that omits `worker:` entirely behaves exactly as it did before this
1336
- feature existed — every def in this repo predating `worker:` is
1335
+ that omits `executor:` entirely behaves exactly as it did before this
1336
+ feature existed — every def in this repo predating `executor:` is
1337
1337
  unaffected, byte for byte. The default is applied at validation and
1338
1338
  engine-order-building time, never written back into the parsed def.
1339
- 2. **`worker: command` requires `command:`.** A step (or judge) whose
1340
- effective worker is `'command'` and carries no `command:` is a load-time
1341
- `DefError`: `` step '<name>' has worker 'command' but no command: ``. Any
1342
- other worker string has no such requirement — `command:` is only ever
1343
- validated when the worker is literally `'command'`.
1344
- 3. **`worker: agent` (explicit) requires a non-empty `body:`.** This check is
1345
- deliberately scoped to an *explicit* `worker: agent`, not the *defaulted*
1346
- value — i.e. `validateDef` checks `l.worker === 'agent'`, never
1347
- `(l.worker ?? 'agent') === 'agent'`. That distinction matters: plenty of
1339
+ 2. **`executor: command` requires `command:`.** A step (or judge) whose
1340
+ effective executor is `'command'` and carries no `command:` is a load-time
1341
+ `DefError`: `` step '<name>' has executor 'command' but no command: ``. Any
1342
+ other executor string has no such requirement — `command:` is only ever
1343
+ validated when the executor is literally `'command'`.
1344
+ 3. **`executor: agent` (explicit) requires a non-empty `body:`.** This check is
1345
+ deliberately scoped to an *explicit* `executor: agent`, not the *defaulted*
1346
+ value — i.e. `validateDef` checks `l.executor === 'agent'`, never
1347
+ `(l.executor ?? 'agent') === 'agent'`. That distinction matters: plenty of
1348
1348
  existing fixtures and generator-only steps rely on `buildStep`'s
1349
- empty-body default and never write `worker:` at all. Checking the
1349
+ empty-body default and never write `executor:` at all. Checking the
1350
1350
  defaulted value would retroactively break every one of them. Checking
1351
1351
  only the explicit form catches the actual mistake this rule exists for —
1352
- someone opts into `worker: agent` on purpose and forgets the prompt —
1352
+ someone opts into `executor: agent` on purpose and forgets the prompt —
1353
1353
  without touching a single pre-existing def.
1354
1354
  4. **`command:` and `spec:` are otherwise opaque.** `command` is
1355
1355
  shape-checked as a string (`asString`); `spec` is shape-checked as a plain
@@ -1361,37 +1361,37 @@ letting it surface as a confusing runtime stall.
1361
1361
  contents" philosophy as `x:`, just scoped to one step instead of the
1362
1362
  whole def.
1363
1363
 
1364
- **The optional `workers:` allow-list.** A definition can declare `workers:
1364
+ **The optional `executors:` allow-list.** A definition can declare `executors:
1365
1365
  [agent, command, …]` at the top level — a typo guard, nothing more. When
1366
- present, `validateDef` rejects any step or judge whose *effective* worker
1366
+ present, `validateDef` rejects any step or judge whose *effective* executor
1367
1367
  (after the `?? 'agent'` default is applied) isn't in the list. This runs
1368
- **after** the default, deliberately: a def that declares `workers: [command]`
1369
- (excluding `'agent'` on purpose) still fails a step that omits `worker:`
1370
- entirely, because that step's effective worker is `'agent'` and `'agent'`
1368
+ **after** the default, deliberately: a def that declares `executors: [command]`
1369
+ (excluding `'agent'` on purpose) still fails a step that omits `executor:`
1370
+ entirely, because that step's effective executor is `'agent'` and `'agent'`
1371
1371
  isn't in the list. This is the intended behavior — once a def opts into the
1372
1372
  allow-list, it's exhaustive, and a step relying on the silent default doesn't
1373
- get a free pass around it. A def with no `workers:` key accepts any worker
1374
- string; there is no engine-wide registry of valid worker types to check
1373
+ get a free pass around it. A def with no `executors:` key accepts any executor
1374
+ string; there is no engine-wide registry of valid executor types to check
1375
1375
  against.
1376
1376
 
1377
- **Pass-through.** `worker`, `command`, and `spec` all ride `buildOrder` onto
1378
- the emitted `Order` untouched — `Order.worker`, `Order.command`, `Order.spec`
1377
+ **Pass-through.** `executor`, `command`, and `spec` all ride `buildOrder` onto
1378
+ the emitted `Order` untouched — `Order.executor`, `Order.command`, `Order.spec`
1379
1379
  — the same pass-through contract as `Order.model` and `Order.x`. A step that
1380
1380
  never sets them emits an order with all three fields absent, identical to
1381
1381
  before this feature existed.
1382
1382
 
1383
1383
  **Judges get the same fields, for free.** §24's `synthesizeJudgeSteps` turns
1384
1384
  each `judges:` entry into an ordinary `StepDef` — so a judge entry accepting
1385
- `worker:`/`command:`/`spec:` and having the exact same `validateDef` rules
1385
+ `executor:`/`command:`/`spec:` and having the exact same `validateDef` rules
1386
1386
  apply to it isn't a separate code path, it's the same rules running against
1387
1387
  an already-existing synthesized step. A judge can therefore be a
1388
1388
  deterministic check (a script's exit code) instead of an LLM verdict, without
1389
1389
  any new validation logic. Note the pre-existing, orthogonal judge
1390
1390
  requirement — every judge needs `body:` or `bodyFile:` regardless of
1391
- `worker:` — still applies; a `worker: command` judge still declares a
1391
+ `executor:` — still applies; a `executor: command` judge still declares a
1392
1392
  `body:`, it's simply unread by a non-agent dispatcher.
1393
1393
 
1394
- **Scope notes**, mirroring §27.3's: `worker`/`command`/`spec` are additive
1394
+ **Scope notes**, mirroring §27.3's: `executor`/`command`/`spec` are additive
1395
1395
  and inert — a definition that never sets any of the three is unchanged in
1396
1396
  behavior and in `hashDef` terms. They live on the same two authored,
1397
1397
  engine-fired shapes as `x:` (a normal step, and — new here — a judge entry),
package/docs/embedding.md CHANGED
@@ -6,8 +6,9 @@ on an `Engine` and prints the results as JSON. Everything it does, a host
6
6
  process can do **in-process** — and get the lifecycle back as typed objects
7
7
  rather than JSON on stdout.
8
8
 
9
- This document covers the in-process API: the one-call factory, the worker step,
10
- in-memory definitions, lifecycle/concurrency, and **push-style events** so a host
9
+ This document covers the in-process API: the one-call factory, the worker step
10
+ (the loop a Step Agent — or your own host code — runs), in-memory definitions,
11
+ lifecycle/concurrency, and **push-style events** so a host
11
12
  can react the instant the graph advances instead of polling.
12
13
 
13
14
  ## The one-call factory
@@ -83,7 +84,7 @@ const status = engine.status(wf); // { done, debts, eligible, blocked, inFligh
83
84
  Each `order` is self-contained: `workflow` (the instance it belongs to — see
84
85
  deep tick below), `prompt`, `consumes` (the captured green inputs), `owes` (the
85
86
  owed outputs + their accumulated reason threads), plus
86
- `inputs`/`outputs`/`model`/`worker`/`command`/`spec`. A consumer rejecting an
87
+ `inputs`/`outputs`/`model`/`executor`/`command`/`spec`. A consumer rejecting an
87
88
  upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
88
89
  cascade and stall liveness behave exactly as they do under the CLI, because
89
90
  it's the same engine.
@@ -110,28 +111,28 @@ one `TickResult` belongs to the instance you ticked; each order carries its own
110
111
  (CLI `--shallow`) stays the deliberate single-instance escape hatch when you
111
112
  want exactly the old behavior.
112
113
 
113
- `order.worker` is where dispatch-by-executor-type earns its keep in an
114
+ `order.executor` is where dispatch-by-executor-type earns its keep in an
114
115
  embedder: rather than every order going to the same LLM-driving `runYourWorker`,
115
116
  branch on it before deciding how to run the order.
116
117
 
117
118
  ```ts
118
119
  for (const order of orders) {
119
120
  const result =
120
- order.worker === 'command'
121
+ order.executor === 'command'
121
122
  ? await runCommand(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
122
- : await runYourAgent(order); // default / worker: 'agent' / anything else you handle the same way
123
+ : await runYourAgent(order); // default / executor: 'agent' / anything else you handle the same way
123
124
 
124
125
  const commit = engine.green(wf, order.run, order.outputs[0], result);
125
126
  engine.close(wf, order.run);
126
127
  }
127
128
  ```
128
129
 
129
- `worker`/`command`/`spec` are all optional and opaque — the engine only
130
+ `executor`/`command`/`spec` are all optional and opaque — the engine only
130
131
  shape-checks them at load time (`command` a string, `spec` a plain map) and
131
- never reads their contents itself. `order.worker` is `undefined` when the
132
+ never reads their contents itself. `order.executor` is `undefined` when the
132
133
  step never set it (today's default, unaffected by this feature). See
133
134
  [`docs/design.md` §27.4](design.md) for the full contract and
134
- [`docs/authoring.md`](authoring.md#worker--declaring-the-executor) for how to
135
+ [`docs/authoring.md`](authoring.md#executor--declaring-the-executor) for how to
135
136
  declare it on a step.
136
137
 
137
138
  A runnable version of this lives at [`examples/embed.ts`](../examples/embed.ts):
@@ -1,27 +1,27 @@
1
- # Declarative executor dispatch — demonstrates `worker:`/`command:`/`spec:`
1
+ # Declarative executor dispatch — demonstrates `executor:`/`command:`/`spec:`
2
2
  # (§27.4 of docs/design.md).
3
3
  #
4
- # The engine never executes anything; `worker:` just labels which kind of
4
+ # The engine never executes anything; `executor:` declares which kind of
5
5
  # executor a step's order is for, so the same def can mix an LLM-driven step
6
- # with a deterministic, non-LLM one. `planner` omits `worker:` entirely (the
6
+ # with a deterministic, non-LLM one. `planner` omits `executor:` entirely (the
7
7
  # default, unaffected `'agent'` path — every existing def in this repo stays
8
- # exactly like this). `tester` declares `worker: command` with a real
9
- # `command:` — a runner dispatching this order runs the command instead of an
8
+ # exactly like this). `tester` declares `executor: command` with a real
9
+ # `command:` — a Worker dispatching this order runs the command instead of an
10
10
  # agent, no judgment involved. `tester`'s `result` produce is gated by a
11
11
  # command judge (`ci-gate`): judges can be deterministic too, not just
12
12
  # LLM-based — this one runs a check script and approves/rejects on exit status.
13
13
  #
14
14
  # Drive it:
15
- # wf=$(owenloop create command-worker --provide plan='{"text":"add a cache layer"}' | jq -r .workflow)
16
- # owenloop tick $wf # -> order for `planner` (worker: agent, default)
15
+ # wf=$(owenloop create command-executor --provide plan='{"text":"add a cache layer"}' | jq -r .workflow)
16
+ # owenloop tick $wf # -> order for `planner` (executor: agent, default)
17
17
  # owenloop green $wf <run> reviewed_plan --value '{"approved":true}'
18
- # owenloop tick $wf # -> order for `tester` (worker: command)
18
+ # owenloop tick $wf # -> order for `tester` (executor: command)
19
19
  # owenloop green $wf <run> result --value '{"exitCode":0}'
20
- # owenloop tick $wf # -> order for the `ci-gate` judge (worker: command)
20
+ # owenloop tick $wf # -> order for the `ci-gate` judge (executor: command)
21
21
  # owenloop green $wf <judge-run> result --value '{}' # judge approves -> result goes green
22
22
 
23
- name: command-worker
24
- title: Command-dispatched worker step
23
+ name: command-executor
24
+ title: Command-dispatched executor step
25
25
  description: Mixes an agent step with a deterministic command step and a command judge.
26
26
 
27
27
  inputs:
@@ -32,7 +32,7 @@ steps:
32
32
  - name: planner
33
33
  consumes: [plan]
34
34
  produces: [reviewed_plan]
35
- # worker: omitted here on purpose — the default/common case, completely
35
+ # executor: omitted here on purpose — the default/common case, completely
36
36
  # unaffected by this feature. This step dispatches to an agent exactly
37
37
  # like every step in every other bundled example.
38
38
  body: |
@@ -46,11 +46,11 @@ steps:
46
46
  judges:
47
47
  - name: ci-gate
48
48
  body: "unused by a command judge, but still a required field (§24)" # not read; a command judge acts on exit status, not a prompt
49
- worker: command # deterministic — no judgment, just run the script
49
+ executor: command # deterministic — no judgment, just run the script
50
50
  command: scripts/ci-gate.sh # exit 0 approves, non-zero rejects with its output
51
- worker: command # deterministic — no judgment, just run the script
51
+ executor: command # deterministic — no judgment, just run the script
52
52
  command: npm test # opaque to the engine; the dispatcher runs this
53
53
  spec: # opaque config for the dispatcher; engine never reads it
54
54
  timeout: 300
55
55
  workdir: .
56
- body: "" # not required for worker: command (no agent prompt)
56
+ body: "" # not required for executor: command (no agent prompt)
@@ -0,0 +1,338 @@
1
+ # compile-dev-playbook — the playbook compiler, developer-task edition.
2
+ #
3
+ # Compiles playbooks for repeatable DEVELOPMENT tasks — SDK integrations,
4
+ # service setup, infra additions — from live vendor documentation. The
5
+ # research sources (official docs, changelogs), the verification vocabulary
6
+ # (test suites, exit codes, lint gates), and the judge criteria are all
7
+ # dev-flavored on purpose; a different domain (business SOPs, compliance
8
+ # processes) deserves its own variant with equally sharp domain judges, not
9
+ # a genericized version of this one. The spine (scout -> distill invariants
10
+ # vs ephemera -> compile -> gate -> test-drive -> human-gated publish) is
11
+ # domain-invariant and is the part to extract via include: when a second
12
+ # domain variant exists.
13
+ #
14
+ # Treats documentation as source code and a workflow def as the compiled
15
+ # artifact: research a repeatable task across live docs, distill the knowledge
16
+ # into invariants (what must always be true) vs ephemera (what changes with
17
+ # versions), compile that into a new owenloop def, and refuse to publish it
18
+ # until it lints clean, survives an adversarial gate-sharpness review, and has
19
+ # actually been test-driven against the engine. Staleness becomes a rebuild:
20
+ # re-run this workflow on the same brief and diff the output.
21
+ #
22
+ # Workspace contract (for whatever conducts this):
23
+ # - Conduct from a scratch workspace dir. The `draft` step writes the
24
+ # generated def to ./build/<name>.yaml in that workspace.
25
+ # - `npx owenloop` must resolve (the lint judge and the test drive shell out
26
+ # to it).
27
+ # - Agent workers need file read/write and web access; the def_draft judges
28
+ # read the drafted YAML from disk at the path carried in the artifact.
29
+ #
30
+ # Drive it:
31
+ # wf=$(owenloop create compile-dev-playbook \
32
+ # --provide brief='{"task":"add Stripe subscription billing to a Node/TypeScript app","category":"billing"}' \
33
+ # | jq -r .workflow)
34
+ # owenloop tick $wf # ... conduct to done (e.g. with the owenloop-conduct skill)
35
+ # # `approval` is a human gate before publish. Flying solo? Pre-approve at create:
36
+ # # --provide approval='{"approved_by":"alex"}'
37
+ # # Otherwise the instance parks blocked on it — durably, in SQLite — until:
38
+ # # owenloop provide $wf approval --value '{"approved_by":"alex"}'
39
+
40
+ name: compile-dev-playbook
41
+ title: Playbook compiler (developer tasks)
42
+ description: >
43
+ Research a repeatable development task (SDK integration, service setup,
44
+ infra addition) across live documentation and compile the knowledge into a
45
+ validated, gate-checked, test-driven owenloop workflow def ("playbook"),
46
+ publishable to a library or hub.
47
+
48
+ executors: [agent, command] # typo guard: any other executor value is a load error
49
+
50
+ x:
51
+ category: meta
52
+ motto: docs are source; the def is the compiled artifact
53
+
54
+ inputs:
55
+ - name: brief
56
+ seedOwed: true
57
+ schema:
58
+ type: object
59
+ required: [task]
60
+ properties:
61
+ task: { type: string, description: "What the playbook automates, e.g. 'add Stripe subscription billing to a Node/TypeScript app'" }
62
+ stack: { type: string, description: "Target stack/context assumptions, if any" }
63
+ category: { type: string, description: "Hub category, e.g. billing | auth | infra | ops" }
64
+ notes: { type: string, description: "Anything else: scope cuts, org conventions, publish destination" }
65
+
66
+ - name: approval
67
+ seedOwed: true
68
+ producer: human
69
+ schema:
70
+ type: object
71
+ required: [approved_by]
72
+ properties:
73
+ approved_by: { type: string }
74
+ notes: { type: string }
75
+
76
+ outputs:
77
+ - playbook
78
+
79
+ steps:
80
+ # ── Research ────────────────────────────────────────────────────────────
81
+ - name: scout
82
+ consumes: [brief]
83
+ produces: ["scout.source[]"]
84
+ model: standard
85
+ body: |
86
+ Workflow ${WORKFLOW}, run ${RUN}.
87
+ Find the authoritative sources for the task in `brief`. Prefer, in order:
88
+ official docs (setup/integration guides, API references), official
89
+ changelogs or release notes (to see what moved recently), then credible
90
+ community material only where official docs are thin.
91
+ `emit` each source as {url, title, kind, why} where kind is one of
92
+ official | changelog | community and `why` says what this source is
93
+ expected to contribute. `seal` once official docs cover the core flow
94
+ AND at least one source speaks to recency (changelog/release notes).
95
+ Do not emit more than ~10 sources — this is a scout, not a crawl.
96
+
97
+ - name: read
98
+ consumes: ["scout.source[$i]"]
99
+ produces: ["scout.source[$i].extract"]
100
+ parallel: 6
101
+ model: fast
102
+ body: |
103
+ Workflow ${WORKFLOW}, run ${RUN}, element ${INDEX}.
104
+ Fetch and read this ONE source. Extract, grounded strictly in what the
105
+ page actually says (no memory, no invention):
106
+ - steps: the procedure the source prescribes, in order
107
+ - invariant_candidates: things that must be TRUE for the integration
108
+ to be correct/safe, regardless of SDK version (e.g. "webhook
109
+ signatures must be verified")
110
+ - pitfalls: warnings, deprecations, common mistakes the source calls out
111
+ - versioning: API/SDK versions, dates, anything that smells ephemeral
112
+ - verifications: anything checkable by a command or test (exit codes,
113
+ CLI verbs, test recipes, dashboard states)
114
+ - human_actions: anything only a human can do (create an account,
115
+ approve a dashboard setting, supply a credential)
116
+ Green `.extract` with those fields plus the source url. If the source is
117
+ dead, paywalled, or off-topic, `retract scout.source[${INDEX}]` instead —
118
+ it drops out of the distillation entirely.
119
+
120
+ # ── Distill: invariants vs ephemera ─────────────────────────────────────
121
+ - name: distill
122
+ consumes: [brief, "scout.source[*].extract"]
123
+ produces:
124
+ - name: knowledge
125
+ schema:
126
+ type: object
127
+ required: [invariants, ephemera, human_inputs, verifications, sources]
128
+ properties:
129
+ invariants:
130
+ type: array
131
+ minItems: 3
132
+ items:
133
+ type: object
134
+ required: [claim, verify_by, sources]
135
+ properties:
136
+ claim: { type: string }
137
+ why: { type: string }
138
+ verify_by: { type: string, description: "How a workflow gate could check this: a command, a judge criterion, a schema" }
139
+ sources: { type: array, items: { type: string }, minItems: 1 }
140
+ ephemera:
141
+ type: array
142
+ items:
143
+ type: object
144
+ required: [detail, source]
145
+ properties:
146
+ detail: { type: string, description: "Version-bound specifics: SDK calls, current API versions, exact snippets" }
147
+ source: { type: string }
148
+ human_inputs:
149
+ type: array
150
+ items:
151
+ type: object
152
+ required: [name, what]
153
+ properties:
154
+ name: { type: string }
155
+ what: { type: string }
156
+ verifications:
157
+ type: array
158
+ minItems: 2
159
+ items:
160
+ type: object
161
+ required: [what, how]
162
+ properties:
163
+ what: { type: string }
164
+ how: { type: string, description: "command | judge | schema — and the concrete check" }
165
+ sources:
166
+ type: array
167
+ items: { type: string }
168
+ judges:
169
+ - name: altitude
170
+ model: strong
171
+ body: |
172
+ Judge `knowledge` for altitude discipline — the one rule that
173
+ keeps compiled playbooks from going stale:
174
+ - Every invariant must be a WHAT-MUST-BE-TRUE claim, durable
175
+ across SDK versions. Reject if any invariant is code-level
176
+ how-to (exact function names, snippets, current API
177
+ versions) — that material belongs in `ephemera`.
178
+ - Every invariant must carry a usable `verify_by` — something
179
+ a workflow gate could actually check. "Be careful" is not a
180
+ verification. Reject vague ones, naming them.
181
+ - Reject if `human_inputs` is empty but any extract mentioned
182
+ accounts, credentials, or dashboard actions.
183
+ Otherwise approve. Rejections must name the offending entries.
184
+ - name: grounding
185
+ inputs: true
186
+ body: |
187
+ You can see the source extracts `knowledge` was distilled from.
188
+ Cross-check: every invariant's `sources` must point at extracts
189
+ that actually support the claim. Reject any invariant that is
190
+ unsupported by, or contradicts, the extracts — cite which.
191
+ Otherwise approve.
192
+ maxAttempts: 3
193
+ model: strong
194
+ body: |
195
+ Workflow ${WORKFLOW}, run ${RUN}.
196
+ Distill every surviving source extract into `knowledge` — the invariant
197
+ model of this task, per the schema. The discipline that matters:
198
+ invariants are what must be true in ANY correct implementation
199
+ (durable); ephemera are today's specifics (SDK calls, versions) and are
200
+ recorded only as pointers back to sources — the compiled playbook will
201
+ cite them, never hardcode them. Merge duplicates across sources; where
202
+ sources conflict, prefer official and newer, and note the conflict.
203
+
204
+ # ── Compile ──────────────────────────────────────────────────────────────
205
+ - name: draft
206
+ consumes: [brief, knowledge]
207
+ produces:
208
+ - name: def_draft
209
+ schema:
210
+ type: object
211
+ required: [name, path, summary, gates]
212
+ properties:
213
+ name: { type: string, description: "the generated def's name:" }
214
+ path: { type: string, description: "where the YAML was written, e.g. build/<name>.yaml" }
215
+ summary: { type: string }
216
+ gates: { type: array, minItems: 2, items: { type: string }, description: "the enforced gates the def carries, one line each" }
217
+ judges:
218
+ - name: lints-clean
219
+ executor: command
220
+ command: npx owenloop lint --defs build
221
+ spec: { workdir: "." }
222
+ body: unused by a command judge; exit 0 approves, non-zero rejects with the lint output
223
+ - name: gate-sharpness
224
+ bodyFile: judges/gate-sharpness.md
225
+ model: strong
226
+ - name: security
227
+ bodyFile: judges/security.md
228
+ model: strong
229
+ maxAttempts: 4
230
+ model: strong
231
+ body: |
232
+ Workflow ${WORKFLOW}, run ${RUN}.
233
+ Compile `knowledge` into a complete owenloop workflow def for the task
234
+ in `brief`. Write the YAML to build/<name>.yaml (create build/ if
235
+ needed), then green `def_draft` with {name, path, summary, gates} — the
236
+ YAML itself lives on disk, not in the artifact.
237
+
238
+ Compilation rules — each is checked by a judge, so cutting corners just
239
+ buys you a rejection:
240
+ 1. FRESHNESS: the generated def's FIRST step must consume the def's
241
+ seeded task input and produce a plan grounded in reading the current
242
+ official docs (cite the source URLs from `knowledge` in its body).
243
+ The playbook forces doc-reading; it never substitutes for it.
244
+ 2. INVARIANTS → STRUCTURE: every invariant in `knowledge` must be
245
+ carried by the def's structure — a step with a schema'd produce, a
246
+ judge, or a command gate. An invariant that survives only as prose
247
+ in a body is a compile error.
248
+ 3. GATES: every entry in `knowledge.verifications` becomes an enforced
249
+ gate — `executor: command` with the check command where deterministic
250
+ (tests run and pass = exit code), a judge otherwise. List each in
251
+ `def_draft.gates`.
252
+ 4. HUMAN MOMENTS: every entry in `knowledge.human_inputs` becomes a
253
+ seedOwed input with a schema — the instance parks until a human
254
+ provides it. Never model these as agent steps. Secrets are
255
+ referenced by name (secret-manager key, env var name), never carried
256
+ as values.
257
+ 5. EPHEMERA: never hardcode version-bound specifics. Where the
258
+ implementer needs them, the step body says "consult <source URL>".
259
+ 6. SIDE EFFECTS: any step with an irreversible external effect declares
260
+ effect: { idempotent: false, onInvalidate: escalate } (or a named
261
+ compensator).
262
+ 7. PROVENANCE: the def carries an x: block — compiled_from (source
263
+ URLs), compiled_for (brief.task), category, compiled_at (today's
264
+ date) — so staleness is visible and a recompile is diffable.
265
+ 8. HOUSE RULES: model tiers by intent (fast/standard/strong), sensible
266
+ maxAttempts, a header comment with drive instructions, and
267
+ `executors:` listing every executor value used.
268
+
269
+ # ── Test drive: a def that has never been driven is a hypothesis ────────
270
+ - name: testdrive
271
+ consumes: [def_draft]
272
+ invalidates: [def_draft]
273
+ produces:
274
+ - name: drive_report
275
+ schema:
276
+ type: object
277
+ required: [verdict, evidence, issues]
278
+ properties:
279
+ verdict: { type: string, enum: [pass] }
280
+ evidence: { type: array, minItems: 2, items: { type: string }, description: "commands run and what they returned" }
281
+ issues: { type: array, items: { type: string } }
282
+ judges:
283
+ - name: honest-drive
284
+ inputs: true
285
+ body: |
286
+ Judge `drive_report` against the def it claims to have driven.
287
+ Reject if: `evidence` does not show BOTH a reachability check
288
+ and a real instance being ticked; the claimed refusal probe is
289
+ missing; or `issues` lists anything that should have been a
290
+ rejection of `def_draft` instead of a pass. A pass without
291
+ evidence is a lie — reject it. Otherwise approve.
292
+ maxAttempts: 3
293
+ model: standard
294
+ body: |
295
+ Workflow ${WORKFLOW}, run ${RUN}.
296
+ Test-drive the def at `def_draft.path` against the real engine. At
297
+ minimum, run and capture:
298
+ 1. npx owenloop check <name> --defs build --assume-provided
299
+ (bounded reachability: deadlocks, stuck steps, dead branches)
300
+ 2. A dry instantiation against a SCRATCH db (never the real one):
301
+ npx owenloop create <name> --defs build --db build/testdrive.db \
302
+ --provide <seed inputs with plausible sample values>
303
+ then tick it and confirm the first order(s) are the doc-reading
304
+ step, not something deeper in the graph.
305
+ 3. A refusal probe: green one schema'd artifact with a deliberately
306
+ malformed value and confirm the engine refuses it
307
+ (schema-rejected), then a valid value and confirm it lands.
308
+ Then EITHER green `drive_report` with verdict "pass" and the evidence
309
+ (commands + observed output), OR — if anything is wrong with the def —
310
+ reject `def_draft` with the concrete failures (this re-arms `draft`
311
+ with your reasons attached) and close this run without greening. Never
312
+ both; never a pass on faith. Clean up the scratch db.
313
+
314
+ # ── Publish (human-gated, irreversible) ─────────────────────────────────
315
+ - name: publish
316
+ consumes: [def_draft, drive_report, approval]
317
+ produces:
318
+ - name: playbook
319
+ schema:
320
+ type: object
321
+ required: [name, path, sources, compiled_at]
322
+ properties:
323
+ name: { type: string }
324
+ path: { type: string, description: "where the published def landed" }
325
+ sources: { type: array, items: { type: string } }
326
+ compiled_at: { type: string }
327
+ effect:
328
+ idempotent: false # publishing is an external write —
329
+ onInvalidate: escalate # if upstream moves later, hold for a human, don't re-publish
330
+ model: fast
331
+ body: |
332
+ Workflow ${WORKFLOW}, run ${RUN}.
333
+ Publish the approved def: copy `def_draft.path` into the playbook
334
+ library (brief.notes may name a destination; default ./playbooks/).
335
+ Verify the copy is byte-identical and its x: provenance block is
336
+ complete. Green `playbook` with {name, path, sources, compiled_at}
337
+ taken from the def's own provenance. Do not edit the def here — publish
338
+ exactly what was judged and driven.
@@ -0,0 +1,39 @@
1
+ # gate-sharpness — reject skills wearing workflow costumes
2
+
3
+ You are judging `def_draft` — a freshly compiled owenloop workflow def. The
4
+ artifact value carries `{name, path, summary, gates}`; read the actual YAML
5
+ from disk at `path`. Your one question: **does this def ENFORCE its playbook,
6
+ or merely describe it?** A def whose guarantees live in prose is a skill
7
+ wearing a workflow costume, and it does not ship.
8
+
9
+ Reject `def_draft` (with the concrete, fixable gaps) if ANY of these hold:
10
+
11
+ 1. **Weak gates.** Fewer than two non-trivial enforced gates across the def —
12
+ where a gate is an `executor: command` step/judge whose exit status decides,
13
+ a judge with a sharp rejection criterion, or a schema on an artifact whose
14
+ shape matters. "The agent will make sure tests pass" in a body is not a
15
+ gate.
16
+ 2. **Prose invariants.** Any must-be-true claim (verify signatures, run the
17
+ tests, don't commit keys) that appears only inside a `body:` with no
18
+ judge, schema, or command backing it.
19
+ 3. **No freshness step.** The first real step does not force reading the
20
+ current official docs (with cited URLs) before any implementation step can
21
+ fire.
22
+ 4. **Hardcoded ephemera.** Bodies that bake in version-bound specifics —
23
+ exact SDK call sequences, current API version strings, copy-paste
24
+ snippets — instead of pointing the implementer at a cited source.
25
+ 5. **Faked human moments.** Account creation, credential provisioning, or
26
+ dashboard approvals modeled as agent steps instead of `seedOwed` inputs.
27
+ 6. **Unmarked side effects.** A step that deploys, publishes, or writes to an
28
+ external system without `effect: { idempotent: false, ... }`.
29
+ 7. **Missing provenance.** No `x:` block with compiled_from / compiled_for /
30
+ compiled_at — an unstamped def is invisible staleness.
31
+ 8. **Self-approval.** Any step that both produces an artifact and is its own
32
+ quality check — the point of this whole system is that the fox does not
33
+ audit the henhouse.
34
+
35
+ Also sanity-check that `def_draft.gates` honestly lists the gates the YAML
36
+ actually declares — an inflated gates list is itself grounds for rejection.
37
+
38
+ If none of the above hold, approve. Do not reject for style, verbosity, or
39
+ choices you would merely have made differently — sharpness, not taste.