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
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
@@ -933,10 +933,71 @@ agents:**
933
933
  ## §25 The model checker (`owenloop check`) — scope
934
934
 
935
935
  `owenloop check <def>` (see `cli.ts` usage) runs a bounded reachability
936
- search over `applyOutcome` transitions in `model.ts`, looking for
937
- deadlocks, stuck artifacts, dead steps, and violations of any declared
938
- invariants. It is a static analysis of a workflow definition's shape, not a
939
- simulation of a running instance.
936
+ search over `applyOutcome` transitions in `model.ts`, looking for stall
937
+ states, true deadlocks, stuck artifacts, dead steps, and violations of any
938
+ declared invariants. It is a static analysis of a workflow definition's
939
+ shape, not a simulation of a running instance.
940
+
941
+ **Stall states vs true deadlocks.** A reachable, non-done state with zero
942
+ eligible firings is classified into exactly ONE of two mutually exclusive
943
+ buckets, by recomputing eligibility as if every freeze were lifted
944
+ (`eligibleFirings(def, arts, undefined, { ignoreFreeze: true })` — "unlimited
945
+ attempts," i.e. what a human `retry` grants):
946
+ - **stall state** (`report.stallStates`) — the recompute yields >= 1 firing:
947
+ the state's ONLY blocker is a frozen/stalled debt — `maxAttempts` reached
948
+ (`isStalled`, §6), `maxSchemaFailures` reached (`isSchemaStalled`, §6/§18),
949
+ or held (`isHeld`, §20). Lifting the freeze re-arms a producer, so the
950
+ line COULD move. This is a by-design human-escalation brake — EXPECTED,
951
+ never a defect, and it never affects the exit code.
952
+ - **true deadlock** (`report.deadlocks`) — the recompute STILL yields zero
953
+ firings: no producer would re-arm even at unlimited attempts. A genuine
954
+ structural dead-end (e.g. a `group:`-blocked or ungreen-input state, or an
955
+ owed input with no producer). This is folded into `hasDefiniteDefect` and
956
+ makes `check` exit nonzero — but only when the search was exhaustive
957
+ (`!report.bounded`), since a tight `--max-collection`/`--max-states` cap
958
+ can otherwise manufacture a spurious no-moves state.
959
+
960
+ The freeze-lift recompute ONLY lifts the `frozen()` guard — it does not
961
+ bypass group-exclusivity (`groupBlockingWinner`), input-green gates, or
962
+ `isDebt`. A state blocked by a group winner or an ungreen input classifies as
963
+ a true deadlock, not a stall state, even if some artifact elsewhere also
964
+ happens to be frozen.
965
+
966
+ Separately, `report.stuck` records reachable states that have a stalled
967
+ debt (`maxAttempts`/`maxSchemaFailures`/held) BUT still have >= 1 eligible
968
+ firing — a brake tripped on one branch while the line can still move on
969
+ another. This is informational only, never a defect on its own, and a
970
+ no-moves state is never listed here (it lands in `stallStates` or
971
+ `deadlocks` instead) — so no single state is ever double-listed across
972
+ `stuck`, `stallStates`, and `deadlocks`.
973
+
974
+ Dead steps — a step name that never appears as a firing in any explored
975
+ transition — are split into two categories with different severity, via a
976
+ static `canEverFire(step, def)` check (`model.ts`) that needs no search
977
+ bounds at all:
978
+ - **structurally dead** (`report.structurallyDeadSteps`) — `canEverFire` is
979
+ false: the step can NEVER fire, regardless of `--max-depth`/
980
+ `--max-states`. This is a genuine wiring defect (e.g. a reduce-mode step
981
+ with no singleton produce to discharge). It is always a *definite*
982
+ finding — bounds-independent by construction — so it is folded into
983
+ `hasDefiniteDefect` and makes `check` exit nonzero, the same way an
984
+ invariant violation does.
985
+ - **unreached within bounds** (`report.unreachedSteps`) — `canEverFire` is
986
+ true: the step CAN fire in principle, but the bounded search didn't reach
987
+ it before exhausting `--max-states`/`--max-depth`. This is informational
988
+ only, a bounds artifact — it does NOT affect the exit code. Raising the
989
+ search bounds may surface the step firing.
990
+
991
+ `canEverFire` is a sound detector of deadness: it only reports a step as
992
+ structurally dead when certain no firing can ever be pushed for it (mirrors
993
+ `eligibleFirings`'s discharge-set logic per step mode); when uncertain it
994
+ defaults to "can fire," so a step is never wrongly flagged as a wiring
995
+ defect. Most structurally-dead shapes are already caught earlier as hard
996
+ errors by `validateDef` (which `check` runs first and throws on) — the
997
+ residual case `canEverFire` exists to catch is a reduce-mode step whose
998
+ `produces:` has zero singleton entries (and no collection produce either,
999
+ so `validateDef`'s reduce check doesn't trip), which reaches `modelCheck`
1000
+ silently dead.
940
1001
 
941
1002
  Two things it deliberately does not model, and why: **born-rejected
942
1003
  commits** — a stale-CAS refusal (§12.2, §24.4) is a refusal, not a state
@@ -950,14 +1011,27 @@ either of these — it answers "is this graph structurally sound," not "can a
950
1011
  human or a stale commit route around a stall." See README's Testing section
951
1012
  for how `owenloop check` fits alongside the test suite.
952
1013
 
953
- The checker also has no runtime `provide` values, so by default a
954
- `seedOwed: true` input starts owed with no transition that can green it —
955
- reported as a false depth-0 deadlock for a def whose inputs the operator
956
- always supplies via `provide` at `create` time. Pass `--assume-provided`
957
- (`assumeProvided` in `CheckOptions` when calling `modelCheck` directly) to
958
- seed those inputs green instead, modeling "the operator already ran
959
- `provide`." It only affects the initial seed — a genuine deadlock reachable
960
- past the inputs is still reported.
1014
+ The checker also has no runtime `provide` values, so a `seedOwed: true`
1015
+ input has no transition that can green it on its own — without seeding it
1016
+ green some other way, it starts owed and can manufacture a false depth-0
1017
+ deadlock for a def whose inputs the operator always supplies via `provide`
1018
+ at `create` time. `CheckOptions.assumeProvided` (library level, when calling
1019
+ `modelCheck` directly) controls this and **defaults to `false`** — that
1020
+ library default is unchanged by the CLI change below, and is what the
1021
+ `modelCheck` unit tests calling it directly still rely on.
1022
+
1023
+ `owenloop check` (the CLI command), however, now defaults to
1024
+ `assumeProvided: true` — seedOwed inputs are seeded green by default,
1025
+ modeling "the operator already ran `provide` at `create`." This dissolves
1026
+ the false depth-0 deadlock for the common case without the flag. Pass
1027
+ `--strict-inputs` to opt back out to the seedOwed-starts-owed behavior; when
1028
+ that's the *sole* reason for an initial-state deadlock, `owenloop check`
1029
+ also prints a one-line hint naming the responsible seedOwed input(s) and
1030
+ pointing at re-running without `--strict-inputs`. `--assume-provided` is
1031
+ still accepted (never errors) but is now redundant with the default; if both
1032
+ `--strict-inputs` and `--assume-provided` are passed, `--strict-inputs` wins.
1033
+ In all cases, seeding only affects the initial seed — a genuine deadlock
1034
+ reachable past the inputs is still reported.
961
1035
 
962
1036
  ## §26 Declarative exclusive produce-groups (`group:`)
963
1037
 
@@ -1243,39 +1317,39 @@ prefixing untouched (there are no stems inside `x:` to rewrite — it's
1243
1317
  opaque); a child definition's own top-level `x:` stays on the child def and
1244
1318
  is not merged into the parent's.
1245
1319
 
1246
- ### §27.4 `worker:`/`command:`/`spec:` — declaring the executor
1320
+ ### §27.4 `executor:`/`command:`/`spec:` — declaring the executor
1247
1321
 
1248
1322
  `x:` (§27.3) is a namespaced escape hatch for arbitrary external vocabulary.
1249
- `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
1250
1324
  whatever dispatches orders *which kind* of executor a step's order is for. It
1251
1325
  follows the same opaque-passthrough contract as `model` — the engine never
1252
1326
  interprets it, only carries it — but unlike `model` (a free-form quality
1253
- hint) and unlike `x:` (fully unvalidated contents), `worker:` gets two narrow,
1254
- 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
1255
1329
  structural precondition the engine can cheaply catch at load time instead of
1256
1330
  letting it surface as a confusing runtime stall.
1257
1331
 
1258
1332
  **The contract, four clauses:**
1259
1333
 
1260
1334
  1. **Default is `'agent'`, and that default is silent.** A step (or judge)
1261
- that omits `worker:` entirely behaves exactly as it did before this
1262
- 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
1263
1337
  unaffected, byte for byte. The default is applied at validation and
1264
1338
  engine-order-building time, never written back into the parsed def.
1265
- 2. **`worker: command` requires `command:`.** A step (or judge) whose
1266
- effective worker is `'command'` and carries no `command:` is a load-time
1267
- `DefError`: `` step '<name>' has worker 'command' but no command: ``. Any
1268
- other worker string has no such requirement — `command:` is only ever
1269
- validated when the worker is literally `'command'`.
1270
- 3. **`worker: agent` (explicit) requires a non-empty `body:`.** This check is
1271
- deliberately scoped to an *explicit* `worker: agent`, not the *defaulted*
1272
- value — i.e. `validateDef` checks `l.worker === 'agent'`, never
1273
- `(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
1274
1348
  existing fixtures and generator-only steps rely on `buildStep`'s
1275
- empty-body default and never write `worker:` at all. Checking the
1349
+ empty-body default and never write `executor:` at all. Checking the
1276
1350
  defaulted value would retroactively break every one of them. Checking
1277
1351
  only the explicit form catches the actual mistake this rule exists for —
1278
- someone opts into `worker: agent` on purpose and forgets the prompt —
1352
+ someone opts into `executor: agent` on purpose and forgets the prompt —
1279
1353
  without touching a single pre-existing def.
1280
1354
  4. **`command:` and `spec:` are otherwise opaque.** `command` is
1281
1355
  shape-checked as a string (`asString`); `spec` is shape-checked as a plain
@@ -1287,37 +1361,37 @@ letting it surface as a confusing runtime stall.
1287
1361
  contents" philosophy as `x:`, just scoped to one step instead of the
1288
1362
  whole def.
1289
1363
 
1290
- **The optional `workers:` allow-list.** A definition can declare `workers:
1364
+ **The optional `executors:` allow-list.** A definition can declare `executors:
1291
1365
  [agent, command, …]` at the top level — a typo guard, nothing more. When
1292
- present, `validateDef` rejects any step or judge whose *effective* worker
1366
+ present, `validateDef` rejects any step or judge whose *effective* executor
1293
1367
  (after the `?? 'agent'` default is applied) isn't in the list. This runs
1294
- **after** the default, deliberately: a def that declares `workers: [command]`
1295
- (excluding `'agent'` on purpose) still fails a step that omits `worker:`
1296
- 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'`
1297
1371
  isn't in the list. This is the intended behavior — once a def opts into the
1298
1372
  allow-list, it's exhaustive, and a step relying on the silent default doesn't
1299
- get a free pass around it. A def with no `workers:` key accepts any worker
1300
- 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
1301
1375
  against.
1302
1376
 
1303
- **Pass-through.** `worker`, `command`, and `spec` all ride `buildOrder` onto
1304
- 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`
1305
1379
  — the same pass-through contract as `Order.model` and `Order.x`. A step that
1306
1380
  never sets them emits an order with all three fields absent, identical to
1307
1381
  before this feature existed.
1308
1382
 
1309
1383
  **Judges get the same fields, for free.** §24's `synthesizeJudgeSteps` turns
1310
1384
  each `judges:` entry into an ordinary `StepDef` — so a judge entry accepting
1311
- `worker:`/`command:`/`spec:` and having the exact same `validateDef` rules
1385
+ `executor:`/`command:`/`spec:` and having the exact same `validateDef` rules
1312
1386
  apply to it isn't a separate code path, it's the same rules running against
1313
1387
  an already-existing synthesized step. A judge can therefore be a
1314
1388
  deterministic check (a script's exit code) instead of an LLM verdict, without
1315
1389
  any new validation logic. Note the pre-existing, orthogonal judge
1316
1390
  requirement — every judge needs `body:` or `bodyFile:` regardless of
1317
- `worker:` — still applies; a `worker: command` judge still declares a
1391
+ `executor:` — still applies; a `executor: command` judge still declares a
1318
1392
  `body:`, it's simply unread by a non-agent dispatcher.
1319
1393
 
1320
- **Scope notes**, mirroring §27.3's: `worker`/`command`/`spec` are additive
1394
+ **Scope notes**, mirroring §27.3's: `executor`/`command`/`spec` are additive
1321
1395
  and inert — a definition that never sets any of the three is unchanged in
1322
1396
  behavior and in `hashDef` terms. They live on the same two authored,
1323
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):
@@ -262,9 +263,10 @@ all the shared types (`Order`, `CommitResult`, `WorkflowStatus`, `WorkflowDef`,
262
263
  `EngineEvent`, `EngineListener`, …). For most hosts, `createEngine` + the engine methods + the `Order` /
263
264
  `CommitResult` / `WorkflowStatus` types are the whole surface you need.
264
265
 
265
- The index also exports a **read-only credential surface** for hosts that need
266
- to read a stored hub credential through owenloop's own store logic instead of
267
- duplicating it: `readStoredCredential(origin, opts)` returns the `Credential`
266
+ The index also exports a **credential surface** for hosts that need to read,
267
+ write, or refresh a stored hub credential through owenloop's own store logic
268
+ instead of duplicating it. The read entry is `readStoredCredential(origin, opts)`,
269
+ which returns the `Credential`
268
270
  for a hub origin **and slot** (or `null` if none is stored), using the same
269
271
  backend selection as the CLI — macOS Keychain, or the `0600` credentials file
270
272
  elsewhere / with `OWENLOOP_NO_KEYCHAIN=1` (see
@@ -284,8 +286,31 @@ an invalid account name) and `keychainServiceFor` (normalized origin → the
284
286
  keychain service name) let a host address the same slots the CLI does without
285
287
  re-deriving the keying. Slots never fall back to one another: an empty
286
288
  `agent:ci` reads as `null` even when `human` is populated. The function never
287
- logs or echoes the secret, and there is deliberately no write or delete companion on the public
288
- surface — `login`/`logout` remain the only way to store or remove a credential.
289
+ logs or echoes the secret.
290
+
291
+ The write entries let a host store or refresh a credential the same way the CLI
292
+ does, addressing the same slots. All three are **async** and take a `CredentialIO`
293
+ (`{ env, keychain?, fetch? }` — a strict subset of the CLI's own io, so the CLI
294
+ passes its `io` unchanged):
295
+
296
+ - `storeCredential(io, origin, slot, credential)` — writes a credential into a
297
+ slot, merging with the other slots on the same origin (the file backend keeps
298
+ `human` when you write `agent:ci`).
299
+ - `deleteCredential(io, origin, slot)` — removes one slot.
300
+ - `ensureFreshOAuth(io, origin, slot, credential)` — returns the credential if
301
+ it is still fresh (more than 60s from expiry), otherwise refreshes the OAuth
302
+ token over the network and persists the rotated result, returning it.
303
+
304
+ `storeCredential`, `deleteCredential`, and the persist inside `ensureFreshOAuth`
305
+ serialize through the `credentials.lock` file described in
306
+ [where the credential lands](cli.md#hub-login--connect--push--logout): a
307
+ concurrent refresh adopts a token another process already rotated rather than
308
+ double-refreshing and clobbering it. When `OWENLOOP_CREDENTIAL_COMMAND` is set,
309
+ that command owns the credential lifecycle — `storeCredential`/`deleteCredential`
310
+ refuse to write, and `ensureFreshOAuth` refreshes over the network without
311
+ persisting. `login`/`logout` are still the CLI's way to store or remove a
312
+ credential; these exports are the programmatic equivalent for a host embedding
313
+ the engine.
289
314
 
290
315
  One behaviour to handle: when the user has set `OWENLOOP_CREDENTIAL_COMMAND` (an
291
316
  external command that supplies the credential, ahead of both stores — see
@@ -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)