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/CHANGELOG.md CHANGED
@@ -4,6 +4,51 @@ All notable changes to this project are documented here. The format is based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.5.0](https://github.com/typicalday/owenloop/compare/v0.4.1...v0.5.0) (2026-08-04)
8
+
9
+
10
+ ### ⚠ BREAKING CHANGES
11
+
12
+ * **cli:** fold owenwork execution CLI into owenloop work ([#91](https://github.com/typicalday/owenloop/issues/91))
13
+ * **cli:** `owenloop binding rm` now requires a `<pool>` argument (`owenloop binding rm <label> <pool>`), and both `binding new` and `binding rm` print new stdout shapes. `binding new` no longer reports `previousPool`; scripts that read it must use `alreadyBound` / `boundPoolCount` instead. The CLI now requires a hub serving `add_label_binding` and `remove_label_binding`.
14
+
15
+ ### Features
16
+
17
+ * add durable shift daemon ([#92](https://github.com/typicalday/owenloop/issues/92)) ([2c68808](https://github.com/typicalday/owenloop/commit/2c6880891d904067071904a3cfda8461ffc2587d))
18
+ * **cli,mcp:** selectable scopes for agent-identity minting ([#83](https://github.com/typicalday/owenloop/issues/83)) ([f9b7a55](https://github.com/typicalday/owenloop/commit/f9b7a559e9ab8f27bdaf15cf26dd6dcc8968c6a4))
19
+ * **cli:** fold owenwork execution CLI into owenloop work ([#91](https://github.com/typicalday/owenloop/issues/91)) ([1ed865a](https://github.com/typicalday/owenloop/commit/1ed865ae6d03cbb176d81e26f2ecce60a5cebd1c))
20
+ * **cli:** migrate binding commands to many-to-many label bindings ([6ba3cc2](https://github.com/typicalday/owenloop/commit/6ba3cc254f8874f8cb734d596b1b6d267c4b5946))
21
+ * **cli:** owenloop binding new|rm|list — label→pool bindings + author docs ([#85](https://github.com/typicalday/owenloop/issues/85)) ([c561861](https://github.com/typicalday/owenloop/commit/c561861c208d96d576997939e33063db8de1670b))
22
+ * **cli:** owenloop pool new|rm|list, pool member add|rm ([#88](https://github.com/typicalday/owenloop/issues/88)) ([8ad5fab](https://github.com/typicalday/owenloop/commit/8ad5fabc454650fed6f006b8b3b55d001d102d85))
23
+ * **mcp:** add pool tools (list_pools/create_pool/add_pool_member/remove_pool_member) ([#89](https://github.com/typicalday/owenloop/issues/89)) ([be2d667](https://github.com/typicalday/owenloop/commit/be2d6678d7da6de14bdb1a90f99c5077f1b95c86))
24
+
25
+
26
+ ### Bug Fixes
27
+
28
+ * **cli:** unify add/push/check's definite-defect predicate via shared helper ([#81](https://github.com/typicalday/owenloop/issues/81)) ([0a43b99](https://github.com/typicalday/owenloop/commit/0a43b99bf3f7b615d74fe4f3780b775adf8c12a8))
29
+ * correct three vocabulary defects found in post-merge audit ([b43f5f6](https://github.com/typicalday/owenloop/commit/b43f5f696d74e35244ed7a355dcf106ad386f53b))
30
+ * **mcp:** sync presence_ping/list_conductors doc-text with hub behavior (W9.4) ([#87](https://github.com/typicalday/owenloop/issues/87)) ([72fc488](https://github.com/typicalday/owenloop/commit/72fc488c2fab055e64951482ff625483bdb927f1))
31
+ * repair and promote compile-dev-playbook, drop stray FUNDING.yml ([#99](https://github.com/typicalday/owenloop/issues/99)) ([7c78094](https://github.com/typicalday/owenloop/commit/7c780945841eb41467d508cac864b3262d5a8f38))
32
+
33
+ ## [0.4.1](https://github.com/typicalday/owenloop/compare/v0.4.0...v0.4.1) (2026-07-22)
34
+
35
+
36
+ ### Features
37
+
38
+ * **check:** default seedOwed inputs to assumed-provided, add --strict-inputs ([#80](https://github.com/typicalday/owenloop/issues/80)) ([1a0891f](https://github.com/typicalday/owenloop/commit/1a0891f280c5d0ccb942cb29ad734480238d652d))
39
+ * **check:** split dead steps into structurally-dead vs unreached-within-bounds ([#77](https://github.com/typicalday/owenloop/issues/77)) ([f7efb10](https://github.com/typicalday/owenloop/commit/f7efb10f922ea5a0baf04df839ce36fd0c626e82))
40
+ * **check:** split EXPECTED stall states from TRUE deadlocks in owenloop check ([#78](https://github.com/typicalday/owenloop/issues/78)) ([5933a67](https://github.com/typicalday/owenloop/commit/5933a67eeee9e654d3e4ba4c48854f6ef04b83b0))
41
+ * **cli:** agent new — mint an agent token into the credential store ([#75](https://github.com/typicalday/owenloop/issues/75)) ([f115cb9](https://github.com/typicalday/owenloop/commit/f115cb9739be28e29de5a7e1debd1155e4ab4a9f))
42
+ * **cli:** owenloop setup + doctor — shipped auth/setup experience (O4) ([#79](https://github.com/typicalday/owenloop/issues/79)) ([9a10d9a](https://github.com/typicalday/owenloop/commit/9a10d9ac618b6f31a5db5c106e3ae91bf44a3c6d))
43
+ * **defs:** flag silently-dead reduce and evaluator steps in validateDef ([#73](https://github.com/typicalday/owenloop/issues/73)) ([84c81f4](https://github.com/typicalday/owenloop/commit/84c81f46197792fe741bff7d74f5e30a537598d7))
44
+ * **hub:** credential write API + concurrency-safe OAuth refresh ([#71](https://github.com/typicalday/owenloop/issues/71)) ([9514571](https://github.com/typicalday/owenloop/commit/95145718492882cfd1088d540f54d639773e82a7))
45
+ * **mcp:** `owenloop mcp` stdio control-plane server (O2) ([#76](https://github.com/typicalday/owenloop/issues/76)) ([0daa66c](https://github.com/typicalday/owenloop/commit/0daa66c5fd32a64a40ab08ba9b393b77350fb91c))
46
+
47
+
48
+ ### Bug Fixes
49
+
50
+ * **engine:** distinguish absent-from-fingerprint vs moved-version in born-reject reasons ([#74](https://github.com/typicalday/owenloop/issues/74)) ([1567b80](https://github.com/typicalday/owenloop/commit/1567b807accc11a71eb9f2cfd7930224577a67a0))
51
+
7
52
  ## [0.4.0](https://github.com/typicalday/owenloop/compare/v0.3.1...v0.4.0) (2026-07-21)
8
53
 
9
54
 
package/README.md CHANGED
@@ -48,11 +48,11 @@ steps:
48
48
  ```
49
49
 
50
50
  You don't drive this by hand. An orchestrator — an agent skill, a plain
51
- `while` loop, your own code — ticks the engine, hands each job to an agent,
51
+ `while` loop, your own code — ticks the engine, hands each job to a Step Agent,
52
52
  and reports results back. Here's what the engine enforces as that loop runs:
53
53
 
54
54
  1. **The writer cannot start early.** The first tick emits exactly one order —
55
- the researcher's. There is no writer job to hand out, so no eager agent can
55
+ the researcher's. There is no writer job to hand out, so no eager Step Agent can
56
56
  write a report from findings that don't exist. The hope version is a
57
57
  prompt: *"wait until research is complete before writing."*
58
58
 
@@ -63,7 +63,7 @@ and reports results back. Here's what the engine enforces as that loop runs:
63
63
 
64
64
  3. **The report can't approve itself.** When the writer commits `report`, it
65
65
  lands in `submitted`, not done. The reviewer is a separate order to a
66
- separate agent — one that never saw the writer's reasoning. A rejection
66
+ separate Step Agent — one that never saw the writer's reasoning. A rejection
67
67
  re-arms the writer with the reviewer's reasons attached to its next job.
68
68
  The hope version: *"review your work before finishing"* — the fox
69
69
  auditing the henhouse.
@@ -140,7 +140,7 @@ Two things make this more than running steps in dependency order:
140
140
  the inputs it was built from are still green and unchanged. Re-run an early step and
141
141
  everything built on it quietly falls back to a debt — no code required to invalidate it.
142
142
  - **Rejections carry reasons.** When a reviewer rejects an output, the text rides along.
143
- The next job for the producer shows *why* it's being asked again, so the agent has
143
+ The next job for the producer shows *why* it's being asked again, so the Step Agent has
144
144
  the feedback in hand. (Three flavors: a reviewer's **judgment**, the engine's own
145
145
  **schema** refusal of a malformed value, and **structural** knock-backs from a
146
146
  change cascading downstream.)
@@ -158,7 +158,7 @@ Two things make this more than running steps in dependency order:
158
158
  *width* — a producer can emit any number of elements — but the wiring graph
159
159
  itself (which steps exist, what each consumes and produces) is fixed when
160
160
  the definition loads, not mutable while an instance runs.
161
- - **Not a command runner.** `worker:`/`command:` label which kind of
161
+ - **Not a command runner.** `executor:`/`command:` declare which kind of
162
162
  executor an order is for and carry a command string through untouched —
163
163
  the engine never shells out, executes, or interprets it. Actually running
164
164
  anything is always the dispatcher's job, on the other side of `tick`.
@@ -247,7 +247,7 @@ to a human, or run a compensating step instead of silently re-firing. See
247
247
 
248
248
  `model: fast | standard | strong | strongest` declares intent, not a vendor
249
249
  id — the engine passes it through untouched to whatever dispatches your
250
- workers. A portable workflow says "this step needs strong judgment"; the
250
+ Step Agents. A portable workflow says "this step needs strong judgment"; the
251
251
  host binds that to whatever model it runs on. `strong` is a high-capability
252
252
  workhorse tier, not the host's single most capable model — that's what the
253
253
  opt-in `strongest` tier is for, reserved for the rare step where nothing less
@@ -256,17 +256,17 @@ will do. See
256
256
 
257
257
  ### Worker dispatch
258
258
 
259
- `worker: agent | command | …` declares which kind of executor a step's order
259
+ `executor: agent | command | …` declares which kind of executor a step's order
260
260
  is for — the default (`agent`, silent when omitted) is unaffected; every
261
261
  def written before this feature stays byte for byte the same. Opt a step
262
- into `worker: command` and give it a `command:` string to switch it to a
262
+ into `executor: command` and give it a `command:` string to switch it to a
263
263
  deterministic executor instead of an LLM — the engine never runs it, only
264
264
  carries it through on the order for your dispatcher to branch on. An
265
265
  optional `spec:` map carries further opaque config (a timeout, a working
266
266
  directory), and a judge entry accepts the same fields, so a quality gate can
267
267
  be a script's exit code instead of a verdict. See
268
- [`docs/authoring.md`](docs/authoring.md#worker--declaring-the-executor) and
269
- [`command-worker.yaml`](examples/workflows/command-worker.yaml).
268
+ [`docs/authoring.md`](docs/authoring.md#executor--declaring-the-executor) and
269
+ [`command-executor.yaml`](examples/workflows/command-executor.yaml).
270
270
 
271
271
  ### Event subscription — for embedding
272
272
 
@@ -295,14 +295,12 @@ looks like:
295
295
  - **Your own harness** — a `while` loop, a cron job, a CI stage: tick, run
296
296
  each order with whatever executes your work (an agent CLI, an API call, a
297
297
  script), report, repeat. Fully deterministic dispatch if you want it —
298
- see [Embedding it](#embedding-it) for the in-process version. A reference
299
- dispatcher/conductor, owenwork, is available separately — the engine core
300
- ships no host harness of its own.
301
- - **An agent as the orchestrator** — point any tool-using agent (Claude Code,
298
+ see [Embedding it](#embedding-it) for the in-process version. The root `owenloop shift` command is the standing Shift runtime — the engine core still ships no host harness of its own.
299
+ - **A Prime Agent as the orchestrator** — point any tool-using agent (Claude Code,
302
300
  Codex, Gemini CLI, anything that can run a shell command) at the CLI and
303
301
  tell it to drive the instance to done. A slash command or skill that wraps
304
302
  this turns "run the release workflow" into one line.
305
- - **An agent structuring its own work, inline** — mid-task, an agent authors
303
+ - **A Prime Agent structuring its own work, inline** — mid-task, the Prime Agent authors
306
304
  a throwaway workflow, drives itself through it, and deletes it: the engine
307
305
  as scratch discipline rather than standing infrastructure.
308
306
 
@@ -323,14 +321,14 @@ patterns ready-made:
323
321
 
324
322
  ## Quick start
325
323
 
326
- Install the owenloop skills for whatever agent you use — Claude Code, Codex,
324
+ Install the owenloop skills for whatever Prime Agent you use — Claude Code, Codex,
327
325
  Cursor, and most others:
328
326
 
329
327
  ```sh
330
328
  npx skills add typicalday/owenloop
331
329
  ```
332
330
 
333
- Then ask your agent for what you want:
331
+ Then ask your Prime Agent for what you want:
334
332
 
335
333
  > Use owenloop-author to build me a workflow that researches a topic, writes
336
334
  > a report, and doesn't accept it until an independent reviewer signs off —
@@ -342,17 +340,40 @@ fresh subagent, relaying knock-backs, and escalating stalls to you. Already
342
340
  have a def? *"Conduct the report workflow"* hands it to
343
341
  [`owenloop-conduct`](skills/owenloop-conduct/SKILL.md). The engine itself
344
342
  arrives via `npx owenloop` (Node ≥ 22.13 required) — no clone, no build, no
345
- environment variables, no CLI verbs to memorize.
343
+ environment variables, no CLI verbs to memorize. The same package also includes
344
+ the execution-side companion; use `owenloop work <subcommand>` for lower-level
345
+ execution tasks. There is no separate `owenwork` package or binary.
346
+
347
+ For a foreground local shift, start the daemon in one terminal. Run the client
348
+ commands from another terminal:
349
+
350
+ ```sh
351
+ # Terminal 1: foreground daemon
352
+ owenloop shift start alpha
353
+
354
+ # Terminal 2: client calls
355
+ owenloop shift next
356
+ owenloop shift status
357
+ owenloop shift end
358
+ ```
359
+
360
+ `shift start` requires at least one named crew unless you pass `--all`
361
+ explicitly; `--all` serves all Crews for the Scoped Identity. `shift next` waits
362
+ up to 90 seconds by default. For flags, JSON output, daemon behavior, and exit
363
+ codes, see the [`shift` reference](docs/cli.md#shift--foreground-daemon-and-client).
346
364
 
347
365
  **Want to see or drive the machinery yourself?** Everything above goes
348
366
  through the same small CLI (`create`, `tick`, `green`, `reject`, …).
349
367
  [`docs/cli.md`](docs/cli.md) has the full command reference and a hand-driven
350
368
  walkthrough of a pipeline — including a rejection knock-back and a stall —
351
- and [`examples/workflows`](examples/workflows) has seven runnable defs, from a
369
+ and [`examples/workflows`](examples/workflows) has seventeen runnable defs, from a
352
370
  minimal review loop ([`delivery`](examples/workflows/delivery.yaml)) to a
353
- full production line ([`ship`](examples/workflows/ship.yaml)) and a
371
+ full production line ([`ship`](examples/workflows/ship.yaml)), a
354
372
  collections-heavy research pipeline
355
- ([`research`](examples/workflows/research.yaml)). Full YAML grammar:
373
+ ([`research`](examples/workflows/research.yaml)), and a compiler that turns
374
+ live vendor docs into a new gate-checked def
375
+ ([`compile-dev-playbook`](examples/workflows/compile-dev-playbook.yaml)).
376
+ Full YAML grammar:
356
377
  [`docs/authoring.md`](docs/authoring.md). Driving it from your own code:
357
378
  [Embedding it](#embedding-it).
358
379
 
@@ -360,7 +381,7 @@ Want someone else's workflow defs instead of writing your own?
360
381
  `owenloop add <owner>/<repo>` fetches a public GitHub repo's `workflows/**`,
361
382
  validates every def, and installs them locally with pinned provenance — see
362
383
  the `add` entry in [`docs/cli.md`](docs/cli.md). An installed def's steps later
363
- run with your workers' full privileges and owenloop never executes them itself,
384
+ run with your Step Agents' full privileges and owenloop never executes them itself,
364
385
  so install only sources you trust, and pin a commit SHA (`@<sha>`) for anything
365
386
  you re-add — the [trust model](docs/cli.md#add--installing-shared-workflow-defs-from-github)
366
387
  is spelled out there.
@@ -370,9 +391,31 @@ the CLI (loopback OAuth, or a pasted token via `--with-token`; the credential
370
391
  goes into the macOS Keychain or a `0600` file, never the repo, and is verified
371
392
  against the hub before it's ever stored), `owenloop connect` binds the project
372
393
  to a hub, and `owenloop push` publishes your defs — idempotent against the
373
- hub's own def hashes, so an unchanged re-push is a no-op. See the
394
+ hub's own def hashes, so an unchanged re-push is a no-op. `owenloop agent new
395
+ <name>` mints a Scoped Identity on the hub and stores its token in slot
396
+ `agent:<name>` without ever printing it. See the
374
397
  [Hub](docs/cli.md#hub-login--connect--push--logout) section in `docs/cli.md`.
375
398
 
399
+ Setting up a machine from scratch? `owenloop setup` may sign you in as a human
400
+ and, when needed, mint or rekey and store a Scoped Identity. Setup writes only
401
+ `hubOrigin` into the execution settings file, preserving the other keys. The
402
+ file is `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is
403
+ set to a non-blank value; otherwise `$HOME/.config/owenloop/settings.json`. For
404
+ a non-default account,
405
+ setup only prints the `OWENLOOP_ACCOUNT=<name>` instruction. Setup probes the
406
+ Claude Code plugin and, when it is missing, prints the manual commands
407
+ `claude plugin marketplace add owenloop` and
408
+ `claude plugin install owenloop@owenloop`; setup does not install the plugin.
409
+ `owenloop doctor` is the read-only counterpart: it checks each piece and prints a
410
+ `✓`/`✗` line with the remedy. See [`setup`](docs/cli.md#setup--onboard-a-machine)
411
+ and [`doctor`](docs/cli.md#doctor--check-a-machines-install) in `docs/cli.md`.
412
+
413
+ Driving the hub from an MCP host instead? `owenloop mcp` serves the hub control
414
+ plane to a local MCP host (Claude Code) over stdio — MCP hosts spawn it, you
415
+ don't run it yourself — authenticating as your logged-in human credential and
416
+ never surfacing a token to the model. See the
417
+ [`mcp`](docs/cli.md#mcp--stdio-control-plane-server-for-mcp-hosts) section in `docs/cli.md`.
418
+
376
419
  ---
377
420
 
378
421
  ## Requirements
@@ -430,10 +473,18 @@ since. The changes that need operator or embedder attention:
430
473
  [trust model](docs/cli.md#add--installing-shared-workflow-defs-from-github).
431
474
  A hub origin now holds one credential per named **slot** (`--as
432
475
  human|agent|agent:<account>`), and credentials stored under the earlier keying
433
- are not read — there is no migration, so re-run `owenloop login`. Setting
476
+ are not read — there is no migration, so re-run `owenloop login`. `owenloop
477
+ agent new <name>` mints an agent token straight into slot `agent:<name>`
478
+ without ever printing the secret. Setting
434
479
  `OWENLOOP_CREDENTIAL_COMMAND` instead supplies the credential from a command
435
480
  of your own (a secret manager, or any host without a keychain); it takes
436
481
  precedence over both stores and fails loudly rather than falling back.
482
+ Embedders can now read, write, and refresh a hub credential programmatically
483
+ through the package's exported credential surface (`readStoredCredential`,
484
+ `storeCredential`, `deleteCredential`, `ensureFreshOAuth`, `CredentialIO`);
485
+ concurrent OAuth refreshes are serialized by a `credentials.lock` file so a
486
+ token rotation can't clobber a fresher one — see
487
+ [What's exported](docs/embedding.md#whats-exported).
437
488
  - **Max-lease cap is now opt-in.** There is no default lease ceiling; anyone who
438
489
  relied on the brief post-0.2.1 default cap must set `maxLeaseMs` (or a
439
490
  per-step `maxLease`) explicitly.
@@ -459,7 +510,7 @@ const wf = engine.createInstance('delivery', {
459
510
  provide: { proposal: { text: 'add dark mode' } },
460
511
  });
461
512
 
462
- // the worker loop: tick → run → report
513
+ // the Step Agent loop: tick → run → report
463
514
  const { orders } = engine.tick(wf);
464
515
  for (const order of orders) {
465
516
  const result = await runYourAgent(order); // ← your domain
@@ -553,6 +604,28 @@ a re-provided input while leaving a healthy graph and a terminal output untouche
553
604
  a malformed value is rejected rather than greened, a corrected value greens on the same
554
605
  open job, repeated failures trip the stall and a `retry` clears it.
555
606
 
607
+ `owenloop check <def>` runs a bounded static reachability search over a workflow
608
+ definition and reports dead steps (never seen firing) split by severity: steps that
609
+ can NEVER fire regardless of search bounds are **structurally dead** — a real wiring
610
+ defect, reported nonzero exit — while steps that CAN fire but the bounded search
611
+ just didn't reach are **unreached within bounds** — informational only, exit 0.
612
+ It also splits every reachable non-done, no-moves state into exactly one of two
613
+ buckets: a **stall state** — the state's only blocker is a frozen/stalled debt
614
+ (maxAttempts / maxSchemaFailures / held); recomputing eligibility with the freeze
615
+ lifted (a human `retry` = unlimited attempts) shows a producer would re-arm and the
616
+ line could move — this is an EXPECTED, by-design human-escalation brake and never
617
+ fails the check — versus a **true deadlock** — the same recompute STILL yields no
618
+ moves, a genuine structural dead-end, which fails the check nonzero when the search
619
+ is exhaustive. See [`docs/design.md` §25](docs/design.md#25-the-model-checker-owenloop-check--scope)
620
+ for the full breakdown.
621
+
622
+ By default, `seedOwed` inputs are assumed provided (modeling the operator's `provide`
623
+ already having run at create), so a def whose only initial gate is an unprovided seeded
624
+ input no longer reports a false `True deadlocks ... (initial state)` and nonzero exit.
625
+ `--strict-inputs` restores the seeded-inputs-start-owed behavior; when that's the sole
626
+ blocker, it also prints a one-line hint naming the seedOwed input(s) responsible.
627
+ `--assume-provided` is still accepted but is now a no-op (redundant with the default).
628
+
556
629
  ---
557
630
 
558
631
  ## Design reference
package/bin/owenloop.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // Thin shim: all real logic lives in src/cli.ts (so it stays testable) and is
3
- // shipped compiled to dist/cli.js. Node cannot type-strip files under
3
+ // shipped compiled to dist/src/cli.js. Node cannot type-strip files under
4
4
  // node_modules, so the published package runs plain JS, not TypeScript source.
5
- import { mainAsync } from '../dist/cli.js';
5
+ import { mainAsync } from '../dist/src/cli.js';
6
6
 
7
7
  mainAsync(process.argv.slice(2)).then((code) => process.exit(code));
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Brief rendering + the born-bound work-holder MCP mount, for the `agent-run`
3
+ * worker (Phase 3).
4
+ *
5
+ * Two pure functions, no I/O:
6
+ *
7
+ * - `renderBrief(templateContent, spec)` — the SAME four-token substitution the
8
+ * legacy stamp path performs when it writes a per-order Step Agent file,
9
+ * minus the file. The worker hands the result straight to
10
+ * `HarnessAdapter.start` as `StartArgs.brief`.
11
+ * - `buildOwenloopMcp(spec)` — the `{command, args}` stdio mount for owenloop's
12
+ * own work-holder MCP surface, byte-identical to the `mcpServers.owenloop`
13
+ * literal the legacy host adapter injects into stamped frontmatter today.
14
+ *
15
+ * WHY THE TOKENS ARE DECLARED HERE AND NOT IMPORTED (plan D4): the legacy
16
+ * host-adapter module under `src/adapters/` is what Phase 5 deletes, and it is
17
+ * vendor-named. Importing from it would point new code at a module on its way
18
+ * out. The duplication is deliberate and `test/agent-brief.test.ts` asserts the
19
+ * two sets are equal strings, so it cannot drift silently.
20
+ *
21
+ * Phase 4 adds a third pure function, `renderRejection` — see its own header.
22
+ *
23
+ * CREDENTIAL STANCE: `buildOwenloopMcp` puts NO credential in argv. The mount
24
+ * carries `--as <account>` — a Scoped Identity *selector*, not a secret — and
25
+ * the mounted work-holder resolves its own bearer from owenloop's credential
26
+ * store. `test/agent-brief.test.ts` asserts this. `renderRejection` reads only
27
+ * `OrderPacket.owes`, which carries no credential either, and
28
+ * `test/agent-rejection.test.ts` asserts that too. The separate, environmental
29
+ * `OWENLOOP_TOKEN` inheritance problem — Phase 3 pointed it at Phase 4, Phase 4
30
+ * re-deferred it — is CLOSED as of Phase 6: `filterOwenloopEnv`
31
+ * (`src/harness/child-env.ts`) is an allowlist over the `OWENLOOP_*` namespace,
32
+ * both adapters pass their child `env` through it, and `agent-run` stopped
33
+ * honouring the override on its own side in the same commit so the two sides
34
+ * cannot authenticate as different principals. See `docs/agent-runner.md`.
35
+ */
36
+ import type { OrderPacket } from '../hub/types.ts';
37
+ /** The composite `<workflow>/<run>` order id token. */
38
+ export declare const ORDER_TOKEN = "__OWENLOOP_ORDER__";
39
+ /** The hub origin token. */
40
+ export declare const ORIGIN_TOKEN = "__OWENLOOP_ORIGIN__";
41
+ /** The Scoped Identity account token. */
42
+ export declare const ACCOUNT_TOKEN = "__OWENLOOP_ACCOUNT__";
43
+ /** The dispatching Shift's self-declared id token (advisory only). */
44
+ export declare const SHIFT_TOKEN = "__OWENLOOP_SHIFT__";
45
+ /**
46
+ * Everything the four-token substitution and the MCP mount need.
47
+ *
48
+ * `run` is the BARE run id; it composes with `workflow` into the
49
+ * `<workflow>/<run>` composite every hub verb wants. `shiftId` is advisory
50
+ * attribution only (D8/INV-82) and absent resolves to the empty string.
51
+ */
52
+ export interface BriefSpec {
53
+ workflow: string;
54
+ run: string;
55
+ origin: string;
56
+ account: string;
57
+ shiftId?: string;
58
+ }
59
+ /**
60
+ * Substitute the four dispatch tokens into a step template.
61
+ *
62
+ * `split(...).join(...)` rather than a regex replace, mirroring the legacy
63
+ * stamp exactly: it replaces every occurrence and treats the token as a literal
64
+ * (no accidental `$&` expansion from template text the author controls).
65
+ */
66
+ export declare function renderBrief(templateContent: string, spec: BriefSpec): string;
67
+ /**
68
+ * The born-bound work-holder mount handed to `HarnessAdapter.start` as
69
+ * `StartArgs.owenloopMcp`. The adapter mounts it verbatim and never builds it.
70
+ *
71
+ * `--shift=<cid>` is ONE argv element, not two. An absent cid then degrades
72
+ * to the single well-formed string `"--shift="` instead of a dangling flag
73
+ * with no value or a null array entry, which is what `hold`'s parser expects.
74
+ * (The shape originated with the deleted stamp path, which had to survive a YAML
75
+ * args array; it is kept because it is still the correct, unambiguous form.)
76
+ */
77
+ export declare function buildOwenloopMcp(spec: BriefSpec): {
78
+ command: string;
79
+ args: string[];
80
+ };
81
+ /**
82
+ * What `renderRejection` produced, plus the watermark the caller must persist.
83
+ *
84
+ * `message` is `''` EXACTLY WHEN nothing new needed saying. The caller treats
85
+ * that as "cold-start with the ordinary brief", never as "resume with an empty
86
+ * message" — a resume that says nothing spends a whole turn to communicate
87
+ * nothing.
88
+ *
89
+ * `deliveredReasonAt` is the largest `ReasonEntry.at` included in `message`, or
90
+ * `undefined` when `message` is empty. It becomes `SessionRecord.deliveredReasonAt`
91
+ * on the row written for the attempt this message opened.
92
+ */
93
+ export interface RejectionDelta {
94
+ message: string;
95
+ deliveredReasonAt?: number;
96
+ /** How many reason entries the message actually carries. Lets a caller log or
97
+ * assert the delta size without re-parsing the rendered text. */
98
+ count: number;
99
+ }
100
+ /** Options for `renderRejection`. */
101
+ export interface RejectionSpec {
102
+ /** The re-offered packet. Only `owes` is read. */
103
+ packet: Pick<OrderPacket, 'owes'>;
104
+ /**
105
+ * The `at` of the newest reason ALREADY delivered into this session, from the
106
+ * last `SessionRecord` for this `(workflow, run, step)`. Absent means nothing
107
+ * has been delivered yet, so every reason is new — which is the correct read
108
+ * for a record written before Phase 4 added the field.
109
+ */
110
+ deliveredReasonAt?: number;
111
+ /**
112
+ * Restrict rendering to these owed paths. Absent renders a section for EVERY
113
+ * owed path that has new reasons, which is what a re-offer owing several paths
114
+ * needs (one section per path, still delta-only, still one watermark).
115
+ */
116
+ paths?: readonly string[];
117
+ }
118
+ /** Rough token budget for the cold-replay brief, per the Phase 4 plan. */
119
+ export declare const REPLAY_TOKEN_BUDGET = 100000;
120
+ /** chars/4 — the cheap, deliberately approximate token estimate. Nothing here
121
+ * needs a real tokenizer: the cap exists to avoid a pathological brief, not to
122
+ * hit a byte-exact ceiling. */
123
+ export declare function estimateTokens(text: string): number;
124
+ /**
125
+ * Render the REJECTION DELTA — the whole point of Phase 4.
126
+ *
127
+ * THE CENTRAL DESIGN POINT: this message is SHORT, and it deliberately does NOT
128
+ * contain the brief. The session being resumed already holds the original brief,
129
+ * the file reads, the tool results and the prior submission — that is the entire
130
+ * reason the worker resumes instead of restarting. Re-sending the brief would
131
+ * spend exactly the tokens this phase exists to save, and would leave the model
132
+ * with two copies of its instructions and no way to tell which is current.
133
+ *
134
+ * WHAT IT MAY NOT CONTAIN, and why each is named rather than left to judgement:
135
+ * - `brief` / `material.templateContent` / `packet.prompt` — see above.
136
+ * - `packet.consumes` and any submit hint — the resumed session already has them.
137
+ * - any credential material. `OrderPacket.owes` carries none, and this function
138
+ * reads nothing else, so the property holds by construction rather than by
139
+ * filtering. `test/agent-rejection.test.ts` asserts it anyway.
140
+ *
141
+ * REASON SELECTION, restated from `docs/agent-runner.md` (c): the reasons come
142
+ * from `OrderPacket.owes[].reasons`, filtered to `at > deliveredReasonAt` and, when
143
+ * `spec.paths` is given, to those owed paths. NEVER from `WorkOrder.feedback` —
144
+ * that is the flattened `whats_next` shape, it carries no `at`, and a shape with
145
+ * no timestamp cannot be diffed against a watermark.
146
+ *
147
+ * PURE: packet + watermark in, string out. No I/O, no clock, no harness.
148
+ */
149
+ export declare function renderRejection(spec: RejectionSpec): RejectionDelta;
150
+ /**
151
+ * Assemble a COLD-REPLAY brief: the ordinary rendered brief plus the same
152
+ * rejection body as a trailing section.
153
+ *
154
+ * Used when resume is impossible (no prior session, a different harness, a dead
155
+ * session, a reaped cwd, a `replay`-tier adapter, or the provider rejecting the
156
+ * resume with `ResumeUnavailableError`). The session is gone, so the brief has to
157
+ * come back — but the reasons still have to arrive, or the fresh agent repeats
158
+ * the rejected submission verbatim.
159
+ *
160
+ * THE CAP. The assembled text is held to roughly `REPLAY_TOKEN_BUDGET` tokens by
161
+ * a chars/4 estimate. When it is over, WHOLE reason entries are dropped from the
162
+ * OLDEST end first and the message says how many were dropped. Never a mid-entry
163
+ * truncation: the kanna `handoff.ts` rule — never orphan a tool result from its
164
+ * call — generalizes here to "never emit half a structured item", because half a
165
+ * reason reads as a complete but different instruction.
166
+ *
167
+ * The BRIEF is never trimmed. If the brief alone exceeds the budget, the brief
168
+ * wins and the rejection section is reduced to as many of the NEWEST reasons as
169
+ * still fit, possibly none — losing the brief would leave the agent with no task
170
+ * at all, which is strictly worse than losing old reasons.
171
+ */
172
+ export declare function renderReplayBrief(brief: string, spec: RejectionSpec): string;