owenloop 0.5.1 → 0.5.2

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 (81) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  13. package/dist/packages/work/src/harness/session-store.js +46 -22
  14. package/dist/packages/work/src/hold/mcp.js +9 -2
  15. package/dist/packages/work/src/hub/client.d.ts +7 -1
  16. package/dist/packages/work/src/hub/client.js +1 -0
  17. package/dist/packages/work/src/hub/types.d.ts +71 -3
  18. package/dist/packages/work/src/roles/agent-run.js +8 -9
  19. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  20. package/dist/packages/work/src/roles/hold.js +39 -8
  21. package/dist/packages/work/src/roles/settings.js +18 -6
  22. package/dist/packages/work/src/roles/shift.js +13 -1
  23. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  24. package/dist/packages/work/src/settings/settings.js +69 -22
  25. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  26. package/dist/packages/work/src/shift/logretention.js +407 -0
  27. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  28. package/dist/packages/work/src/shift/logsink.js +98 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  30. package/dist/packages/work/src/shift/loop.js +250 -12
  31. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  32. package/dist/packages/work/src/shift/protocol.js +14 -0
  33. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  34. package/dist/packages/work/src/shift/runtime.js +229 -6
  35. package/dist/packages/work/src/shift/server.d.ts +13 -0
  36. package/dist/packages/work/src/shift/server.js +61 -36
  37. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  38. package/dist/packages/work/src/shift/spawn.js +158 -12
  39. package/dist/packages/work/src/shift/state.d.ts +25 -0
  40. package/dist/packages/work/src/shift/state.js +29 -5
  41. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  42. package/dist/packages/work/src/shift/truncate.js +73 -0
  43. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  44. package/dist/packages/work/src/submit-proof.js +33 -7
  45. package/dist/packages/work/src/submit-value.d.ts +48 -0
  46. package/dist/packages/work/src/submit-value.js +118 -0
  47. package/dist/packages/work/src/usage.d.ts +1 -1
  48. package/dist/packages/work/src/usage.js +11 -0
  49. package/dist/src/capabilities.d.ts +93 -0
  50. package/dist/src/capabilities.js +101 -0
  51. package/dist/src/cli.js +14 -9
  52. package/dist/src/crypto/records.d.ts +3 -0
  53. package/dist/src/crypto/records.js +11 -0
  54. package/dist/src/defs.js +192 -4
  55. package/dist/src/engine.d.ts +112 -3
  56. package/dist/src/engine.js +224 -28
  57. package/dist/src/hub.d.ts +27 -11
  58. package/dist/src/hub.js +24 -18
  59. package/dist/src/index.d.ts +3 -1
  60. package/dist/src/index.js +4 -1
  61. package/dist/src/mcp/serve.js +11 -4
  62. package/dist/src/model.d.ts +36 -0
  63. package/dist/src/model.js +46 -0
  64. package/dist/src/schemas/index.d.ts +17 -0
  65. package/dist/src/schemas/order.v1.schema.json +17 -3
  66. package/dist/src/store.d.ts +33 -1
  67. package/dist/src/store.js +57 -4
  68. package/dist/src/types.d.ts +102 -2
  69. package/docs/authoring.md +7 -0
  70. package/docs/bundles.md +103 -3
  71. package/docs/cli.md +127 -9
  72. package/docs/crypto.md +23 -7
  73. package/docs/shift-logs.md +642 -0
  74. package/docs/wire-contracts.md +34 -19
  75. package/package.json +1 -1
  76. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  77. package/plugins/claude-code/plugin/.mcp.json +1 -1
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  81. package/dist/packages/work/src/agent/model-policy.js +0 -138
package/docs/cli.md CHANGED
@@ -179,7 +179,7 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
179
179
  ```text
180
180
  owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
181
181
  [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
182
- [--cache-dir <p>] [--state-dir <p>]
182
+ [--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
183
183
  ```
184
184
 
185
185
  At least one named crew is required unless `--all` is present. `--all` and
@@ -199,6 +199,92 @@ one loop sweep and exits instead of keeping the foreground daemon running.
199
199
  | `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
200
200
  | `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
201
201
  | `--state-dir <p>` | socket and child-state root; precedence is flag, then `OWENLOOP_STATE_DIR`, then `settings.stateDir`, then `$XDG_STATE_HOME/owenloop/exec`, then `$HOME/.local/state/owenloop/exec`; the socket is `shift.sock` inside this directory |
202
+ | `--log-dir <p>` | where `shift.log` and each `<run>.log` are written; precedence is flag, then `OWENLOOP_SHIFT_LOG_DIR`, then `settings.shiftLogDir`, then the resolved state directory |
203
+ | `--log-max-age <ms>` | worker-log retention, swept once at startup; precedence is flag, then `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, then `settings.shiftLogMaxAgeMs`, then `1209600000` (14 days). `0` reaps every completed run's log at the next startup; there is no value that disables the sweep, and `shift.log` is never reaped |
204
+
205
+ **On-disk logs.** A running shift appends its dispatch record to
206
+ `<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
207
+ and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
208
+ process. A log directory that cannot be created costs the logs, never the
209
+ dispatch: the shift reports it once on stderr and serves with logging disabled.
210
+ Full field-by-field contract, retention rules, and uploader notes in
211
+ [`docs/shift-logs.md`](shift-logs.md).
212
+
213
+ **One harness per shift.** A shift has no per-order harness switch and no
214
+ `--harness` flag. It never puts `--harness` on a worker's command line; each
215
+ `agent-run` child resolves its own adapter, in this order:
216
+
217
+ 1. its own `--harness` flag — which a shift never supplies;
218
+ 2. `OWENLOOP_HARNESS` in the environment the child inherits, which is the
219
+ shift's environment;
220
+ 3. the `harness:` field on the verified step definition;
221
+ 4. the first registered adapter.
222
+
223
+ Rank 2 is the operator's control. Export `OWENLOOP_HARNESS` in the shell that
224
+ starts the shift and every agent order that shift dispatches runs on that
225
+ adapter. To run two adapters at once, start two shifts:
226
+
227
+ ```bash
228
+ OWENLOOP_HARNESS=claude-code XDG_CONFIG_HOME=~/.config/owenloop-shifts/claude owenloop shift start build --state-dir ~/.local/state/owenloop/claude
229
+ ```
230
+
231
+ ```bash
232
+ OWENLOOP_HARNESS=codex XDG_CONFIG_HOME=~/.config/owenloop-shifts/codex owenloop shift start build --state-dir ~/.local/state/owenloop/codex
233
+ ```
234
+
235
+ Both shifts may serve the SAME crew. The hub does not route by harness — it
236
+ offers an order to any shift whose crew is bound to the order's capability, and
237
+ whichever shift claims it first runs it on its own adapter.
238
+
239
+ **Per-shift `XDG_CONFIG_HOME` is not optional when the adapters differ.** The
240
+ settings file resolves from `XDG_CONFIG_HOME` (see above), and it carries
241
+ `capabilityModels` — a map of composed capability to `{model, effort}` whose
242
+ model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
243
+ adapters need different model ids for the same capability, so they need
244
+ different settings files, so they need different `XDG_CONFIG_HOME` values. A
245
+ shared config directory would give both shifts one adapter's model ids, and the
246
+ shift holding the wrong adapter fails at the vendor API on its first order.
247
+
248
+ Give each shift its own `--state-dir` as well. The state directory holds the
249
+ control socket (`shift.sock`), and a second shift starting against a socket
250
+ another shift already owns is refused.
251
+
252
+ **`capabilityModels` — which model serves which capability.** The hub decides
253
+ WHAT grade of work an order is; it composes the step's capability with the run's
254
+ depth modifier and stamps the result on the order (`builder` at the `deep`
255
+ modifier becomes `builder:deep`). It never decides which model serves that
256
+ grade. That decision is local, and this map is where the operator makes it:
257
+
258
+ ```json
259
+ {
260
+ "capabilityModels": {
261
+ "builder:deep": { "model": "claude-opus-5", "effort": "xhigh" },
262
+ "builder": { "model": "claude-sonnet-5", "effort": "high" },
263
+ "wise": { "model": "claude-fable-5", "effort": "xhigh" }
264
+ }
265
+ }
266
+ ```
267
+
268
+ Lookup runs two passes over the order's capabilities: every EXACT composed key
269
+ first, then every BARE name part. `builder:deep` takes the first row above;
270
+ `builder:express` has no exact row and falls back to the `builder` row.
271
+ `effort` must be one of `low`, `medium`, `high`, `xhigh`, `max`. The model id is
272
+ never checked against a list — owenloop keeps no registry of which models exist,
273
+ so a model released after your owenloop build still works.
274
+
275
+ A capability with no exact row and no bare row is REFUSED, not run on a default:
276
+ the worker releases the claim, reports the refusal to the hub, and exits `1`. An
277
+ order carrying no capabilities at all is not refused — it runs on the adapter's
278
+ own default model, which is how capability-silent steps have always run.
279
+
280
+ **Migrating from `tierMap` / `tierProfiles`.** Both keys are removed. A settings
281
+ file that still contains either one fails to load with an error naming
282
+ `capabilityModels`; the shift does not start. This is deliberate — a shift that
283
+ ignored the old keys would have no capability map at all and would refuse every
284
+ order it claimed, hours later and far from the cause. Rewrite the tier rungs as
285
+ capability rows: whatever `tierProfiles.strongest` pointed at becomes the
286
+ `{model, effort}` of your `:deep` rows, and whatever `standard` pointed at
287
+ becomes the bare rows.
202
288
 
203
289
  A clean start or `--once` completion exits `0`. `owenloop shift --help` also
204
290
  exits `0`. Runtime failures such as credential reads or socket/runtime setup
@@ -260,14 +346,46 @@ returns promptly when an event is queued, the wait expires, or the shift
260
346
  explicitly ends. A normal timeout exits `0` and prints the current capacity
261
347
  object, for example `{ "cap": 3, "free": 3, "running": 0, "events": [] }`.
262
348
  Successful responses use the same capacity shape and may include queued event
263
- objects. For `dispatched`, `reaped`, and `failed`, `kind` is either `exec` or
264
- `agent-run`:
349
+ objects.
350
+
351
+ **Every event carries the same three envelope fields**, in addition to whatever
352
+ its own `type` defines:
353
+
354
+ | field | meaning |
355
+ |---|---|
356
+ | `ts` | ISO-8601 UTC with milliseconds, e.g. `2026-08-13T18:04:11.412Z` |
357
+ | `shift` | the shift's human name — `clock_in` can change it between events |
358
+ | `shiftId` | `shf_<uuid>`, the shift process incarnation; stable for the process |
359
+
360
+ The envelope is omitted from the per-type examples below for brevity; it is
361
+ never omitted on the wire. For `dispatched`, `reaped`, and `failed`, `kind` is
362
+ either `exec` or `agent-run`:
265
363
 
266
364
  - `dispatched`: `{ "type": "dispatched", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "pid": 123 }`
267
365
  - `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
268
366
  - `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
367
+ - `bundle-miss`: `{ "type": "bundle-miss", "workflow": "...", "def": "..." }` — a legacy order named a def with no cached bundle, so it was left for hub pickup
368
+ - `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`); display `message`
269
369
  - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
270
370
 
371
+ Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
372
+ is how they survive the daemon. **Four further record types exist in
373
+ `shift.log` and are never delivered over the socket** — `parked`, `capacity`,
374
+ `hub-error`, and `event-queue-overflow`.
375
+
376
+ An idle `shift next` must block until there is work to report, and each of those
377
+ four would satisfy it with news that no work moved: a startup record, a report
378
+ that the shift is full, a failed call to the hub, or a record about the socket
379
+ queue itself. `parked` and `capacity` are also redundant on the wire — the
380
+ response above already carries live `cap`, `free`, and `running`, which is
381
+ exactly what a `capacity` record restates. `hub-error` is level-triggered at the
382
+ poll interval, so an unreachable hub would otherwise fill the 1000-slot socket
383
+ FIFO and evict the `dispatched`, `failed` and `reaped` records a parked client
384
+ is actually waiting for. In `shift.log`, which is append-only and unbounded, all
385
+ four are load-bearing: they are the only way to tell an idle shift from a
386
+ saturated one, and the only record of every failed hub call. See
387
+ [`docs/shift-logs.md`](shift-logs.md).
388
+
271
389
  `gate` is a reserved protocol shape for a future local representation of a
272
390
  pending hub gate. Production code does not construct live hub gate events yet;
273
391
  the local FIFO test and drill scope are recorded in
@@ -1691,7 +1809,7 @@ allowed) re-reads the route table as it stands at that moment.
1691
1809
  - **Adding.** Running `capability bind` on a capability that is **already bound** ADDS the
1692
1810
  named crew — it never displaces a crew already bound. Adding widens who can
1693
1811
  serve the capability, live at the next poll of every in-flight run using it. Re-adding
1694
- a pair that is already there is a normal success, not an error (`alreadyRouted:
1812
+ a pair that is already there is a normal success, not an error (`alreadyBound:
1695
1813
  true`).
1696
1814
  - **Removing.** Running `capability unbind` removes exactly ONE pair. If the capability still
1697
1815
  has other live routes, it simply routes to a narrower set and nothing pauses.
@@ -1718,9 +1836,9 @@ id; the CLI does no crew lookup and performs no client-side validation of either
1718
1836
  argument (the hub is the enforcement of record).
1719
1837
 
1720
1838
  **Adding is idempotent per pair.** Re-adding a `(capability, crew)` pair that is
1721
- already bound is a normal success — the hub answers `200` with `alreadyRouted:
1839
+ already bound is a normal success — the hub answers `200` with `alreadyBound:
1722
1840
  true` and changes nothing (the original row keeps its creator and timestamp).
1723
- `routedCrewCount` reports how many **live** crews the capability binds after the write.
1841
+ `boundCrewCount` reports how many **live** crews the capability binds after the write.
1724
1842
 
1725
1843
  ### `capability unbind <capability> <crew>`
1726
1844
 
@@ -1781,7 +1899,7 @@ works. Human progress lines (the two `capability unbind` warnings) go to stderr
1781
1899
 
1782
1900
  | subcommand | stdout |
1783
1901
  |---|---|
1784
- | `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyRouted": false, "routedCrewCount": 2 }` |
1902
+ | `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyBound": false, "boundCrewCount": 2 }` |
1785
1903
  | `capability unbind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crewId": "crw_1", "removed": true, "remainingCrewIds": ["crw_2"] }` |
1786
1904
  | `capability list` | `{ "ok": true, "hub": "<origin>", "routes": [ { "capability": "gpu", "crewId": "crw_1", "crewName": "ml-crew", "createdBy": "u_1", "createdAt": 1738000000000 } ] }` |
1787
1905
 
@@ -1789,9 +1907,9 @@ Every added field carries the **hub's own name**, verbatim — the same words it
1789
1907
  audit log and the web console use — so correlating stdout against them never
1790
1908
  needs a translation step.
1791
1909
 
1792
- - `alreadyRouted` (`capability bind`) — was this exact `(capability, crew)` pair already
1910
+ - `alreadyBound` (`capability bind`) — was this exact `(capability, crew)` pair already
1793
1911
  bound before the call? `false` means the pair was created by it.
1794
- - `routedCrewCount` (`capability bind`) — how many **live** crews the capability binds
1912
+ - `boundCrewCount` (`capability bind`) — how many **live** crews the capability binds
1795
1913
  after the write. A dangling route routes nothing and is not counted.
1796
1914
  - `removed` (`capability unbind`) — did this call actually remove a pair? `false` is the
1797
1915
  tolerant "it was never bound" case, not an error.
package/docs/crypto.md CHANGED
@@ -164,13 +164,29 @@ canonical JSON payload with `dsseSignSubmission` under the
164
164
  `owenloop-dsse-v1` namespace. The target `proof` request field is the serialized
165
165
  DSSE envelope for that one submitted artifact path.
166
166
 
167
- A judge approval may sign the existing judged version from the claim fingerprint.
168
- A producer submit must not infer a new version from immutable `owes[].version`
169
- or process-local state. The producer requires a retry-safe, hub-issued target
170
- version; without one, the driver submits without a proof and warns once per
171
- process. As of 2026-08-10, the production hub does not carry submit `proof`,
172
- proof acceptance, authoritative producer-version allocation, or downstream
173
- proof projection, so owenloop does not claim end-to-end production proof support.
167
+ A judge approval may sign the existing judged version from the claim fingerprint,
168
+ because the approval attests that version and does not allocate a new one.
169
+
170
+ A producer submit signs `owes[].version`, the target version the hub issues for
171
+ that owed output. The target is the version the next successful commit will
172
+ land (claim-time committed version + 1) — exactly the version the downstream
173
+ consumer passes to `verifyConsumed` as `expectedVersion`. It is never inferred
174
+ from process-local state.
175
+
176
+ Retry-safety is a property of where the target is computed, not of the client.
177
+ The engine computes it inside the claim transaction and persists it with the
178
+ immutable order, so every read of that claim — a reconnect, a retried submit
179
+ after a lost response, a restarted holder — yields the same number. Engine
180
+ refusal paths that leave the run open (a schema reject) do not bump the
181
+ artifact, so the target survives in-claim retries; a refinement is a new claim
182
+ and receives a newly issued target. A stale target fails the consumer's version
183
+ check, which is a refusal, never an admitted unverified value.
184
+
185
+ A target is authoritative only when it is a positive integer: the smallest
186
+ commit any producer can land is v1. An absent target, a `0`, or a non-integer
187
+ is treated as no authoritative metadata — the driver submits without a proof
188
+ and warns once per process, rather than signing a number the consumer is
189
+ guaranteed to reject.
174
190
 
175
191
  The engine does not sign: local `Engine.green` is synchronous and commits inside
176
192
  a synchronous store transaction. `owenloop green` remains deliberately unsigned