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/CHANGELOG.md CHANGED
@@ -4,6 +4,32 @@ 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
+
7
33
  ## [0.4.1](https://github.com/typicalday/owenloop/compare/v0.4.0...v0.4.1) (2026-07-22)
8
34
 
9
35
 
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.
@@ -371,17 +392,23 @@ 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
394
  hub's own def hashes, so an unchanged re-push is a no-op. `owenloop agent new
374
- <name>` mints an agent identity on the hub and stores its token in slot
395
+ <name>` mints a Scoped Identity on the hub and stores its token in slot
375
396
  `agent:<name>` without ever printing it. See the
376
397
  [Hub](docs/cli.md#hub-login--connect--push--logout) section in `docs/cli.md`.
377
398
 
378
- Setting up a machine from scratch? `owenloop setup` converges the whole install
379
- in one idempotent pass — human login, agent credential, owenwork settings, and
380
- the Claude Code plugin — so a re-run on an already-set-up machine writes
381
- nothing. `owenloop doctor` is its read-only counterpart: it checks each piece
382
- and prints a `✓`/`✗` line with the remedy. See
383
- [`setup`](docs/cli.md#setup--converge-a-machines-install) and
384
- [`doctor`](docs/cli.md#doctor--check-a-machines-install) in `docs/cli.md`.
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`.
385
412
 
386
413
  Driving the hub from an MCP host instead? `owenloop mcp` serves the hub control
387
414
  plane to a local MCP host (Claude Code) over stdio — MCP hosts spawn it, you
@@ -483,7 +510,7 @@ const wf = engine.createInstance('delivery', {
483
510
  provide: { proposal: { text: 'add dark mode' } },
484
511
  });
485
512
 
486
- // the worker loop: tick → run → report
513
+ // the Step Agent loop: tick → run → report
487
514
  const { orders } = engine.tick(wf);
488
515
  for (const order of orders) {
489
516
  const result = await runYourAgent(order); // ← your domain
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;
@@ -0,0 +1,193 @@
1
+ /** The composite `<workflow>/<run>` order id token. */
2
+ export const ORDER_TOKEN = '__OWENLOOP_ORDER__';
3
+ /** The hub origin token. */
4
+ export const ORIGIN_TOKEN = '__OWENLOOP_ORIGIN__';
5
+ /** The Scoped Identity account token. */
6
+ export const ACCOUNT_TOKEN = '__OWENLOOP_ACCOUNT__';
7
+ /** The dispatching Shift's self-declared id token (advisory only). */
8
+ export const SHIFT_TOKEN = '__OWENLOOP_SHIFT__';
9
+ /** The composite order id — the only form the hub verbs accept. */
10
+ function composite(spec) {
11
+ return `${spec.workflow}/${spec.run}`;
12
+ }
13
+ /**
14
+ * Substitute the four dispatch tokens into a step template.
15
+ *
16
+ * `split(...).join(...)` rather than a regex replace, mirroring the legacy
17
+ * stamp exactly: it replaces every occurrence and treats the token as a literal
18
+ * (no accidental `$&` expansion from template text the author controls).
19
+ */
20
+ export function renderBrief(templateContent, spec) {
21
+ return templateContent
22
+ .split(ORDER_TOKEN)
23
+ .join(composite(spec))
24
+ .split(ORIGIN_TOKEN)
25
+ .join(spec.origin)
26
+ .split(ACCOUNT_TOKEN)
27
+ .join(spec.account)
28
+ .split(SHIFT_TOKEN)
29
+ .join(spec.shiftId ?? '');
30
+ }
31
+ /**
32
+ * The born-bound work-holder mount handed to `HarnessAdapter.start` as
33
+ * `StartArgs.owenloopMcp`. The adapter mounts it verbatim and never builds it.
34
+ *
35
+ * `--shift=<cid>` is ONE argv element, not two. An absent cid then degrades
36
+ * to the single well-formed string `"--shift="` instead of a dangling flag
37
+ * with no value or a null array entry, which is what `hold`'s parser expects.
38
+ * (The shape originated with the deleted stamp path, which had to survive a YAML
39
+ * args array; it is kept because it is still the correct, unambiguous form.)
40
+ */
41
+ export function buildOwenloopMcp(spec) {
42
+ return {
43
+ command: 'owenloop',
44
+ args: [
45
+ 'work',
46
+ 'hold',
47
+ '--order',
48
+ composite(spec),
49
+ '--origin',
50
+ spec.origin,
51
+ '--as',
52
+ spec.account,
53
+ `--shift=${spec.shiftId ?? ''}`,
54
+ '--mcp',
55
+ ],
56
+ };
57
+ }
58
+ /** Rough token budget for the cold-replay brief, per the Phase 4 plan. */
59
+ export const REPLAY_TOKEN_BUDGET = 100_000;
60
+ /** chars/4 — the cheap, deliberately approximate token estimate. Nothing here
61
+ * needs a real tokenizer: the cap exists to avoid a pathological brief, not to
62
+ * hit a byte-exact ceiling. */
63
+ export function estimateTokens(text) {
64
+ return Math.ceil(text.length / 4);
65
+ }
66
+ /** One rendered reason line. `kind`/`by` are attribution the model needs to weigh
67
+ * a reason; `text` is the reason itself. */
68
+ function reasonLine(index, r) {
69
+ return `${index}. [${r.kind}, by ${r.by}] ${r.text}`;
70
+ }
71
+ /**
72
+ * Render the REJECTION DELTA — the whole point of Phase 4.
73
+ *
74
+ * THE CENTRAL DESIGN POINT: this message is SHORT, and it deliberately does NOT
75
+ * contain the brief. The session being resumed already holds the original brief,
76
+ * the file reads, the tool results and the prior submission — that is the entire
77
+ * reason the worker resumes instead of restarting. Re-sending the brief would
78
+ * spend exactly the tokens this phase exists to save, and would leave the model
79
+ * with two copies of its instructions and no way to tell which is current.
80
+ *
81
+ * WHAT IT MAY NOT CONTAIN, and why each is named rather than left to judgement:
82
+ * - `brief` / `material.templateContent` / `packet.prompt` — see above.
83
+ * - `packet.consumes` and any submit hint — the resumed session already has them.
84
+ * - any credential material. `OrderPacket.owes` carries none, and this function
85
+ * reads nothing else, so the property holds by construction rather than by
86
+ * filtering. `test/agent-rejection.test.ts` asserts it anyway.
87
+ *
88
+ * REASON SELECTION, restated from `docs/agent-runner.md` (c): the reasons come
89
+ * from `OrderPacket.owes[].reasons`, filtered to `at > deliveredReasonAt` and, when
90
+ * `spec.paths` is given, to those owed paths. NEVER from `WorkOrder.feedback` —
91
+ * that is the flattened `whats_next` shape, it carries no `at`, and a shape with
92
+ * no timestamp cannot be diffed against a watermark.
93
+ *
94
+ * PURE: packet + watermark in, string out. No I/O, no clock, no harness.
95
+ */
96
+ export function renderRejection(spec) {
97
+ const since = spec.deliveredReasonAt;
98
+ const wanted = spec.paths === undefined ? undefined : new Set(spec.paths);
99
+ const sections = [];
100
+ let newest;
101
+ let count = 0;
102
+ for (const owed of spec.packet.owes) {
103
+ if (wanted !== undefined && !wanted.has(owed.path))
104
+ continue;
105
+ const fresh = owed.reasons.filter((r) => since === undefined || r.at > since);
106
+ // A schema reject with no text is a real shape: the owed entry exists, the
107
+ // reason thread is empty. Filtering to nothing here is what makes the caller
108
+ // cold-start rather than resume with a bare "you were rejected".
109
+ if (fresh.length === 0)
110
+ continue;
111
+ const lines = fresh.map((r, i) => reasonLine(i + 1, r));
112
+ sections.push(`Your submission for \`${owed.path}\` was rejected. Reasons:\n\n${lines.join('\n')}`);
113
+ count += fresh.length;
114
+ for (const r of fresh) {
115
+ if (newest === undefined || r.at > newest)
116
+ newest = r.at;
117
+ }
118
+ }
119
+ if (sections.length === 0)
120
+ return { message: '', count: 0 };
121
+ const message = [
122
+ ...sections,
123
+ 'Revise and submit again to the same path with the same tool. Do not start over —\n' +
124
+ 'keep everything you already have that was not called out above.',
125
+ ].join('\n\n');
126
+ return { message, count, ...(newest !== undefined ? { deliveredReasonAt: newest } : {}) };
127
+ }
128
+ /**
129
+ * Assemble a COLD-REPLAY brief: the ordinary rendered brief plus the same
130
+ * rejection body as a trailing section.
131
+ *
132
+ * Used when resume is impossible (no prior session, a different harness, a dead
133
+ * session, a reaped cwd, a `replay`-tier adapter, or the provider rejecting the
134
+ * resume with `ResumeUnavailableError`). The session is gone, so the brief has to
135
+ * come back — but the reasons still have to arrive, or the fresh agent repeats
136
+ * the rejected submission verbatim.
137
+ *
138
+ * THE CAP. The assembled text is held to roughly `REPLAY_TOKEN_BUDGET` tokens by
139
+ * a chars/4 estimate. When it is over, WHOLE reason entries are dropped from the
140
+ * OLDEST end first and the message says how many were dropped. Never a mid-entry
141
+ * truncation: the kanna `handoff.ts` rule — never orphan a tool result from its
142
+ * call — generalizes here to "never emit half a structured item", because half a
143
+ * reason reads as a complete but different instruction.
144
+ *
145
+ * The BRIEF is never trimmed. If the brief alone exceeds the budget, the brief
146
+ * wins and the rejection section is reduced to as many of the NEWEST reasons as
147
+ * still fit, possibly none — losing the brief would leave the agent with no task
148
+ * at all, which is strictly worse than losing old reasons.
149
+ */
150
+ export function renderReplayBrief(brief, spec) {
151
+ const full = renderRejection(spec);
152
+ if (full.message === '')
153
+ return brief;
154
+ const join = (body, dropped) => {
155
+ const note = dropped > 0
156
+ ? `\n\n(${dropped} older rejection reason${dropped === 1 ? '' : 's'} omitted to fit the context budget.)`
157
+ : '';
158
+ return `${brief}\n\n---\n\n${body}${note}`;
159
+ };
160
+ let assembled = join(full.message, 0);
161
+ if (estimateTokens(assembled) <= REPLAY_TOKEN_BUDGET)
162
+ return assembled;
163
+ // Over budget: re-render with progressively fewer reasons, oldest dropped
164
+ // first. `ordered` is every candidate entry in ascending `at`, so slicing off
165
+ // the FRONT drops the oldest and keeps whole entries.
166
+ const since = spec.deliveredReasonAt;
167
+ const wanted = spec.paths === undefined ? undefined : new Set(spec.paths);
168
+ const ordered = spec.packet.owes
169
+ .filter((o) => wanted === undefined || wanted.has(o.path))
170
+ .flatMap((o) => o.reasons)
171
+ .filter((r) => since === undefined || r.at > since)
172
+ .sort((a, b) => a.at - b.at);
173
+ for (let drop = 1; drop <= ordered.length; drop += 1) {
174
+ const keep = new Set(ordered.slice(drop));
175
+ const trimmed = renderRejection({
176
+ ...spec,
177
+ packet: {
178
+ owes: spec.packet.owes.map((o) => ({ ...o, reasons: o.reasons.filter((r) => keep.has(r)) })),
179
+ },
180
+ // The watermark filter already ran; re-applying it is harmless but the
181
+ // `keep` set is now the authority on which entries survive.
182
+ ...(since !== undefined ? { deliveredReasonAt: since } : {}),
183
+ });
184
+ if (trimmed.message === '')
185
+ break;
186
+ assembled = join(trimmed.message, drop);
187
+ if (estimateTokens(assembled) <= REPLAY_TOKEN_BUDGET)
188
+ return assembled;
189
+ }
190
+ // Everything was dropped and it still does not fit — the brief alone is over
191
+ // budget. Return the brief: an agent with a task and no reasons can still work.
192
+ return brief;
193
+ }