owenloop 0.5.8 → 0.5.9
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.
- package/CHANGELOG.md +25 -0
- package/README.md +4 -2
- package/dist/packages/work/src/agent/loop.d.ts +23 -8
- package/dist/packages/work/src/agent/loop.js +48 -6
- package/dist/packages/work/src/consumed-verifier.js +6 -17
- package/dist/packages/work/src/exec/loop.d.ts +1 -1
- package/dist/packages/work/src/exec/loop.js +181 -32
- package/dist/packages/work/src/exec/receipt.d.ts +7 -7
- package/dist/packages/work/src/exec/receipt.js +6 -6
- package/dist/packages/work/src/harness/claude.js +100 -0
- package/dist/packages/work/src/hub/client.d.ts +19 -4
- package/dist/packages/work/src/hub/client.js +7 -3
- package/dist/packages/work/src/hub/types.d.ts +84 -0
- package/dist/packages/work/src/main.js +1 -0
- package/dist/packages/work/src/roles/agent-run.js +19 -22
- package/dist/packages/work/src/roles/exec.js +2 -0
- package/dist/packages/work/src/roles/settings.js +2 -0
- package/dist/packages/work/src/roles/shift.js +14 -2
- package/dist/packages/work/src/roles/util.d.ts +1 -0
- package/dist/packages/work/src/roles/util.js +10 -0
- package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
- package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
- package/dist/packages/work/src/settings/roster.d.ts +84 -0
- package/dist/packages/work/src/settings/roster.js +364 -5
- package/dist/packages/work/src/settings/serving.d.ts +17 -0
- package/dist/packages/work/src/settings/serving.js +79 -0
- package/dist/packages/work/src/settings/settings.d.ts +14 -1
- package/dist/packages/work/src/settings/settings.js +14 -0
- package/dist/packages/work/src/shift/loop.d.ts +108 -5
- package/dist/packages/work/src/shift/loop.js +299 -51
- package/dist/packages/work/src/shift/protocol.d.ts +7 -5
- package/dist/packages/work/src/shift/runtime.d.ts +15 -0
- package/dist/packages/work/src/shift/runtime.js +94 -4
- package/dist/packages/work/src/shift/server.js +2 -0
- package/dist/packages/work/src/shift/spawn.d.ts +17 -2
- package/dist/packages/work/src/shift/spawn.js +16 -13
- package/dist/packages/work/src/shift/state.d.ts +29 -2
- package/dist/packages/work/src/shift/state.js +45 -15
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +7 -1
- package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
- package/dist/packages/work/src/util/modifier-init.js +73 -0
- package/dist/src/bundle/tar.d.ts +9 -4
- package/dist/src/bundle/tar.js +9 -4
- package/dist/src/capabilities.d.ts +6 -0
- package/dist/src/cli.d.ts +14 -1
- package/dist/src/cli.js +687 -75
- package/dist/src/config-dir.d.ts +1 -1
- package/dist/src/config-dir.js +1 -1
- package/dist/src/crypto/index.d.ts +1 -1
- package/dist/src/crypto/index.js +1 -1
- package/dist/src/crypto/org-root.d.ts +30 -12
- package/dist/src/crypto/org-root.js +162 -14
- package/dist/src/crypto/records.d.ts +2 -0
- package/dist/src/crypto/records.js +2 -0
- package/dist/src/defs.d.ts +6 -1
- package/dist/src/defs.js +203 -8
- package/dist/src/engine.d.ts +42 -7
- package/dist/src/engine.js +158 -16
- package/dist/src/index.d.ts +4 -4
- package/dist/src/index.js +2 -2
- package/dist/src/mcp/serve.d.ts +22 -0
- package/dist/src/mcp/serve.js +88 -8
- package/dist/src/model.d.ts +2 -0
- package/dist/src/model.js +32 -25
- package/dist/src/order-resolver.d.ts +1 -0
- package/dist/src/order-resolver.js +8 -1
- package/dist/src/schemas/index.d.ts +11 -0
- package/dist/src/schemas/order.v1.schema.json +7 -1
- package/dist/src/store.d.ts +5 -0
- package/dist/src/store.js +43 -8
- package/dist/src/types.d.ts +40 -3
- package/docs/authoring.md +90 -2
- package/docs/bundles.md +26 -2
- package/docs/cli.md +170 -28
- package/docs/crypto.md +19 -3
- package/docs/design.md +70 -1
- package/docs/routing.md +189 -34
- package/docs/shift-logs.md +20 -9
- package/docs/wire-contracts.md +50 -7
- package/examples/workflows/delivery.yaml +31 -14
- package/examples/workflows/ship.yaml +10 -2
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/docs/cli.md
CHANGED
|
@@ -53,7 +53,7 @@ for the full breakdown.
|
|
|
53
53
|
| `login [--hub <url>] [--with-token] [--as <slot>]` | authenticate the CLI against a hub — loopback OAuth, or `--with-token` from stdin — see [Hub](#hub-login--connect--push--logout) |
|
|
54
54
|
| `connect [--hub <url>] [--as <slot>]` | verify a resolved hub credential and record an optional per-project override in `.owenloop/hub.json` |
|
|
55
55
|
| `push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <url>] [--as <slot>]` | publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (idempotent against the hub's own def hashes) |
|
|
56
|
-
| `start <defName> [--provide name=json …] [--crew <name>] [--title <text>] [--hub <url>]` | start a published workflow on the bound hub with the human credential |
|
|
56
|
+
| `start <defName> [--provide name=json …] [--crew <name>] [--title <text>] [--modifier <name>] [--scope <label>] [--priority <low\|normal\|high>] [--hub <url>]` | start a published workflow on the bound hub with the human credential |
|
|
57
57
|
| `publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <url>]` | pack a canonical workflow bundle and publish a signed publication sidecar, with an optional signed origin sidecar, or an explicitly unsigned marker |
|
|
58
58
|
| `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
|
|
59
59
|
| `agent new <name> [--crews <a,b>] [--scopes <a,b>] [--shift] [--hub <url>]` | mint a new Scoped Identity on the hub and store its token in slot `agent:<name>` — the token is never printed; `--shift` = `--scopes work,run` — see [Hub](#hub-login--connect--push--logout) |
|
|
@@ -73,10 +73,17 @@ for the full breakdown.
|
|
|
73
73
|
| `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>] [--reuse-ssh-key <path>]` | onboard this machine: may store human and Scoped Identity credentials, ensure the three principal signing keys, relay the machine enrollment grant, write only execution-settings `hubOrigin`, and converge the bundled plugins for Claude Code and Codex — see [`setup`](#setup--onboard-a-machine) |
|
|
74
74
|
| `enrollments [--hub <url>]` | read and locally classify the hub's relayed machine enrollment grants; never creates keys or writes the roster — see [`enrollments`](#enrollments--inspect-machine-enrollment) |
|
|
75
75
|
| `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
|
|
76
|
-
| `roster show [crew]` | print the merged **crew roster
|
|
76
|
+
| `roster show [crew]` | print the offline merged **crew roster**, all inspected machine and cached-hub layers, winner provenance, cache age, and shadowed rows |
|
|
77
|
+
| `roster org [--hub <url>]` | read the live hub org-global and per-crew rosters (human credential) |
|
|
78
|
+
| `roster org put <capability> --candidate <harness>:<model>:<effort>… [--crew <name>] [--hub <url>]` | replace one org-global or named crew roster row (human admin credential) |
|
|
79
|
+
| `roster org rm <capability> [--crew <name>] [--hub <url>]` | remove one org-global or named crew roster row (human admin credential) |
|
|
80
|
+
| `roster registry [--hub <url>]` | read the hub's known harnesses, models, and efforts (human credential) |
|
|
81
|
+
| `roster registry put <harness> [--model <model>:<effort,effort…>]… [--display-name <text>] [--hub <url>]` | replace one harness's full hub model snapshot (human admin credential); omit every `--model` to clear it |
|
|
82
|
+
| `roster sync [--hub <url>] [--as agent\|agent:<account>]` | refresh the local hub-roster cache explicitly with the same agent credential a shift uses |
|
|
77
83
|
| `mcp [--hub <url>]` | serve the hub control plane to a local MCP host over stdio — spawned by MCP hosts, not run by humans — see [`mcp`](#mcp--stdio-control-plane-server-for-mcp-hosts) |
|
|
78
84
|
| `shift start <crew...>`, `shift next`, `shift status`, `shift end` | run the foreground shift daemon and its local clients — see [`shift`](#shift--foreground-daemon-and-client) |
|
|
79
85
|
| `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
|
|
86
|
+
| `util modifier-init --default <value>` | choose a modifier from rejection feedback, the order hint, or a default; intended for command steps |
|
|
80
87
|
| `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
|
|
81
88
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
82
89
|
| `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
|
|
@@ -93,7 +100,7 @@ for the full breakdown.
|
|
|
93
100
|
| `reject <wf> <path> --by <author> --text <msg>` | reject an output (re-arms its producer) |
|
|
94
101
|
| `retract <wf> <path> --by <author> --text <msg>` | drop a collection member |
|
|
95
102
|
| `skip <wf> <path> --by <author> --text <msg>` | a step declines its own output |
|
|
96
|
-
| `retry <wf> <path> [--by a] [--text guidance]` | clear a stall
|
|
103
|
+
| `retry <wf> <path> [--by a] [--text guidance] [--hub <url>]` | clear a stall and reset the counter, or answer an `ask` — `--hub` targets a hub-hosted run |
|
|
97
104
|
| `close <wf> <run> [--outcome ok\|no_work\|failed\|skipped] [--summary s]` | release a claimed job |
|
|
98
105
|
| `delete <wf>` | delete an instance and all its rows |
|
|
99
106
|
| `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
|
|
@@ -181,14 +188,14 @@ By default, the execution settings file is `$HOME/.owenloop/settings.json`.
|
|
|
181
188
|
For test or throwaway isolation, `OWENLOOP_CONFIG_DIR` may name an absolute
|
|
182
189
|
directory used verbatim; `XDG_CONFIG_HOME` is not consulted. In the paths below,
|
|
183
190
|
`<config>` means the resolved owenloop config directory. The same directory
|
|
184
|
-
holds `credentials.json`, `allowed_signers`, `org-root.pub`, `
|
|
191
|
+
holds `credentials.json`, `allowed_signers`, `org-root.pub`, `grants/`, and
|
|
185
192
|
`revocations/`.
|
|
186
193
|
|
|
187
194
|
### `shift start <crew...>`
|
|
188
195
|
|
|
189
196
|
```text
|
|
190
197
|
owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
|
|
191
|
-
[--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
|
|
198
|
+
[--cap <n>] [--max-agents <n>] [--exec-reserve <n>] [--local-queue-hold <ms>] [--poll-interval <ms>] [--once]
|
|
192
199
|
[--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
|
|
193
200
|
[--work-root <dir>]...
|
|
194
201
|
```
|
|
@@ -206,6 +213,8 @@ one loop sweep and exits instead of keeping the foreground daemon running.
|
|
|
206
213
|
| `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
|
|
207
214
|
| `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
|
|
208
215
|
| `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
|
|
216
|
+
| `--exec-reserve <n>` | slots inside `--cap` that `agent-run` children may never occupy, so an exec/command order always has room; precedence is flag, then `settings.execReserve`, then `1`. Clamped to `cap - 1`, so a `--cap 1` shift gets no reserve. `0` disables the reserve and lets agents fill the whole cap. This does not raise the total child ceiling — `--cap` still bounds every child. |
|
|
217
|
+
| `--local-queue-hold <ms>` | how long to retain a claim this shift cannot dispatch before returning it to the hub; precedence is flag, then `settings.localQueueHoldMs`, then `0`. The value is clamped to 90 seconds. `0` means the shift never holds an undispatchable claim locally, so another daemon can be offered it immediately. |
|
|
209
218
|
| `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
|
|
210
219
|
| `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
|
|
211
220
|
| `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
|
|
@@ -254,25 +263,44 @@ directories an order is **allowed to name**. Neither derives from the other.
|
|
|
254
263
|
owenloop shift start build --work-root ~/code --work-root /srv/work
|
|
255
264
|
```
|
|
256
265
|
|
|
257
|
-
**Crew roster selection.**
|
|
258
|
-
roster** for capability routing, not the unrelated trust roster of signed
|
|
259
|
-
enrollment grants in `~/.owenloop/roster/`. A selected roster candidate decides
|
|
266
|
+
**Crew roster selection.** A selected roster candidate decides
|
|
260
267
|
the harness, model, and effort for an agent order. Its precedence is:
|
|
261
268
|
|
|
262
|
-
1. the first available candidate in the first matching crew roster
|
|
269
|
+
1. the first available candidate in the first matching crew roster named in
|
|
270
|
+
the hub-stamped `order.crews` sequence;
|
|
263
271
|
2. `owenloop work agent-run --harness` (a local debug override);
|
|
264
272
|
3. the verified step's `x.harness.id`;
|
|
265
273
|
4. the first registered adapter.
|
|
266
274
|
|
|
267
|
-
The shift
|
|
268
|
-
|
|
269
|
-
|
|
275
|
+
The shift advertises its start crews through worker → hub `serve_crews` and
|
|
276
|
+
its derived serving set through `serve_capabilities`. The latter is the raw
|
|
277
|
+
key union from the roster cascade (bare names and exact compounds are both
|
|
278
|
+
preserved), recomputed at startup and on the roughly 15-minute roster refresh;
|
|
279
|
+
it is not operator-set. **Today's hub ignores `serve_capabilities`; the
|
|
280
|
+
hub-side intersect ships separately.** The shift passes no crews to agent
|
|
281
|
+
workers. For a capability-bearing order, the worker resolves rosters only from
|
|
282
|
+
the hub-stamped `order.crews` list, in that stamped order. If the stamp is
|
|
283
|
+
missing, empty, malformed, or cannot be resolved locally, the worker refuses
|
|
284
|
+
and releases the order rather than falling back to the shift's start crews. The
|
|
285
|
+
complete strongest-first cascade for each stamped crew is: machine
|
|
286
|
+
`~/.owenloop/crews/<crew>.json`, machine
|
|
287
|
+
`~/.owenloop/settings.json` `roster`, the cached hub row for that crew, then
|
|
288
|
+
the cached hub org-global row. Hub rows live in a separate
|
|
289
|
+
`~/.owenloop/hub-rosters/` cache directory — never in the D5 trust
|
|
290
|
+
`~/.owenloop/grants/` directory. Each capability row is atomic:
|
|
270
291
|
the stronger layer replaces the weaker candidate array, and candidates are
|
|
271
292
|
tried in listed order. A step's `x.harness.id` is a policy constraint: a row
|
|
272
293
|
whose candidates do not include it is released as
|
|
273
294
|
`incompatible-harness-policy`; no available candidate is
|
|
274
295
|
`unresolvable-capability`.
|
|
275
296
|
|
|
297
|
+
The shift refreshes that hub cache at startup and periodically while parked;
|
|
298
|
+
`owenloop roster sync` is the manual repair path. Failed refreshes never stop a
|
|
299
|
+
shift or refuse an order: a missing or corrupt cache becomes an explicitly
|
|
300
|
+
reported absent layer and the machine rows keep routing. `owenloop roster show`
|
|
301
|
+
is offline by design, so it prints exactly the layers an `agent-run` child can
|
|
302
|
+
see, including fetch age and any lower-priority rows shadowed by a winner.
|
|
303
|
+
|
|
276
304
|
```json
|
|
277
305
|
{
|
|
278
306
|
"roster": {
|
|
@@ -305,6 +333,40 @@ file). `owenloop doctor` adds one line for each present crew roster file,
|
|
|
305
333
|
showing its found/absent layers and registered versus missing candidate
|
|
306
334
|
harnesses.
|
|
307
335
|
|
|
336
|
+
Crew names are data, not filesystem paths. A fresh safe crew keeps the literal
|
|
337
|
+
`~/.owenloop/crews/<crew>.json` filename for rollback compatibility. Unsafe or
|
|
338
|
+
too-wide names use the dedicated codec-only
|
|
339
|
+
`~/.owenloop/crews/.owenloop-machine-roster-codec-namespace-reserved-v1-ownership/`
|
|
340
|
+
directory: short names use a reversible `crew-hex--<lowercase-hex>.json` basename,
|
|
341
|
+
while names too wide for one filesystem component use a bounded
|
|
342
|
+
`crew-hex-hash--…` basename. The current codec's distinct `crew-hex--` prefix
|
|
343
|
+
and lowercase hexadecimal payload keep it disjoint from older base64url files
|
|
344
|
+
and stable on case-insensitive filesystems; explicitly owned older
|
|
345
|
+
`crew--<base64url>.json` files remain readable during migration. Every codec
|
|
346
|
+
file records its exact `crew` identity in
|
|
347
|
+
the JSON document, so a reversible basename alone can never claim an old
|
|
348
|
+
legacy file. Do not derive either filename by hand. The reserved directory
|
|
349
|
+
itself can be the prefix of a valid 64-character nested legacy crew name, so a
|
|
350
|
+
file inside it is codec storage only when its JSON `crew` identity reproduces
|
|
351
|
+
its codec basename; a shorter unowned child remains a legacy path. A complete
|
|
352
|
+
codec path is nevertheless too long to be a hub-valid legacy crew name.
|
|
353
|
+
Existing safe legacy
|
|
354
|
+
`<crew>.json` files — including names containing spaces, colons, percent
|
|
355
|
+
signs, Unicode, and (on POSIX) backslashes — plus any lexically contained
|
|
356
|
+
legacy tree such as `crews/foo/bar.json` for crew `foo/bar` — remain readable
|
|
357
|
+
and take precedence only when their on-disk spelling exactly matches the crew,
|
|
358
|
+
so `Delivery` and `delivery` cannot silently share one strongest layer on a
|
|
359
|
+
case-insensitive filesystem. The short-lived feature-branch directory
|
|
360
|
+
`.owenloop-encoded-rosters/` is treated as codec storage only when a file
|
|
361
|
+
declares the codec basename's exact `crew`; otherwise it remains a legacy
|
|
362
|
+
nested path. A literal crew name that spells an owned historical codec file is
|
|
363
|
+
distinct from that file's declared owner and receives its own current codec
|
|
364
|
+
path, never an alias of the historical strongest layer.
|
|
365
|
+
Routing probes only its requested crew paths. Doctor combines global file
|
|
366
|
+
diagnostics with the verified agent's crew list, so a malformed bounded hash
|
|
367
|
+
file is reported rather than silently disappearing. Traversal-shaped hub crew
|
|
368
|
+
names stay confined to the `crews/` directory.
|
|
369
|
+
|
|
308
370
|
A clean start or `--once` completion exits `0`. `owenloop shift --help` also
|
|
309
371
|
exits `0`. Runtime failures such as credential reads or socket/runtime setup
|
|
310
372
|
exit `1`. Usage and
|
|
@@ -326,6 +388,17 @@ version loops sharing the directory are configured with different total or
|
|
|
326
388
|
agent caps, each loop enforces its own configured limits under the shared lock.
|
|
327
389
|
Use identical cap settings for every loop sharing a state directory.
|
|
328
390
|
|
|
391
|
+
Reconciliation uses that same lock and re-checks record identity before it
|
|
392
|
+
changes anything: an abandoned reservation must still match the observed
|
|
393
|
+
reservation token, a dead child must still have the observed PID, and a
|
|
394
|
+
persisted start gate must still match both the observed PID and gate token. If
|
|
395
|
+
another loop re-dispatches the same run while a stale scan is waiting for the
|
|
396
|
+
lock, the replacement record and gate are preserved and no `abandoned` or
|
|
397
|
+
`reaped` event is reported. Startup reconciliation defers briefly when the
|
|
398
|
+
lock is busy and the poll loop retries it. A worker exit notification releases
|
|
399
|
+
its PID record on every terminal outcome, including a clean exit with status
|
|
400
|
+
`0`; reconciliation remains the crash/restart backstop.
|
|
401
|
+
|
|
329
402
|
Canonical `*.json` child and reservation records are capacity-bearing state.
|
|
330
403
|
Missing records are benign, including a record that disappears between listing
|
|
331
404
|
and read. A truncated, malformed, or unreadable canonical record is not benign:
|
|
@@ -384,7 +457,7 @@ either `exec` or `agent-run`:
|
|
|
384
457
|
- `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
|
|
385
458
|
- `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
|
|
386
459
|
- `bundle-miss`: `{ "type": "bundle-miss", "workflow": "...", "def": "..." }` — a legacy order named a def with no cached bundle, so it was left for hub pickup
|
|
387
|
-
- `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`
|
|
460
|
+
- `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`, `agent-lane-closed`, `dispatch-cap-full`, `agent-cap-full`, `claim-expired`); display `message`. The capacity, expiry, and `agent-lane-closed` reasons return the claim to the hub; malformed and unsupported reasons leave it for the pickup window.
|
|
388
461
|
- `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
|
|
389
462
|
|
|
390
463
|
Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
|
|
@@ -429,11 +502,13 @@ owenloop shift status [--state-dir <p>]
|
|
|
429
502
|
With a daemon, status exits `0` and prints:
|
|
430
503
|
|
|
431
504
|
```json
|
|
432
|
-
{ "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
|
|
505
|
+
{ "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "agent_ceiling": 2, "attended_at": null, "started_at": 1738000000000 }
|
|
433
506
|
```
|
|
434
507
|
|
|
435
|
-
`
|
|
436
|
-
|
|
508
|
+
`agent_ceiling` is the effective maximum number of `agent-run` children after
|
|
509
|
+
applying `--max-agents`, `--cap`, and `--exec-reserve`; command and exec work
|
|
510
|
+
may still use any free slot inside `cap`. `attended_at` remains `null` until the
|
|
511
|
+
first accepted `next` request. Without a daemon, status is still a successful question: it exits `0` and prints
|
|
437
512
|
`{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
|
|
438
513
|
other client/runtime errors exit `1`.
|
|
439
514
|
|
|
@@ -482,6 +557,28 @@ The execution settings file is `<config>/settings.json` (see
|
|
|
482
557
|
| `release --session <id> [options]` | drain a session's held claims |
|
|
483
558
|
| `settings` | print the resolved execution settings file |
|
|
484
559
|
| `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
|
|
560
|
+
| `util modifier-init --default <value>` | print the requested modifier from `OWENLOOP_FEEDBACK`, else `OWENLOOP_MODIFIER`, else the required default |
|
|
561
|
+
|
|
562
|
+
### `util modifier-init`
|
|
563
|
+
|
|
564
|
+
`owenloop util modifier-init --default <value>` is a deterministic helper for
|
|
565
|
+
a command step that produces a bound modifier artifact. It prints one value and
|
|
566
|
+
does no model or harness work. Its precedence is:
|
|
567
|
+
|
|
568
|
+
1. the newest `reject` reason carrying `requested` in `OWENLOOP_FEEDBACK`;
|
|
569
|
+
2. the current order modifier in `OWENLOOP_MODIFIER`;
|
|
570
|
+
3. the required `--default` value.
|
|
571
|
+
|
|
572
|
+
The helper accepts a single-word result only. It reads feedback inline from
|
|
573
|
+
`OWENLOOP_FEEDBACK` or from the temporary path in `OWENLOOP_FEEDBACK_FILE`,
|
|
574
|
+
using the same 64 KiB threshold and collision rule as consumed inputs. Exit 0
|
|
575
|
+
prints the value; exit 2 is a usage error; exit 3 means the feedback could not
|
|
576
|
+
be parsed or the resolved value was invalid.
|
|
577
|
+
|
|
578
|
+
The helper prints the selected word as ordinary stdout. A command artifact is
|
|
579
|
+
submitted as the full `CommandReceipt`; if a workflow binds a field inside a
|
|
580
|
+
command payload, the command must emit the `##owenloop:payload##` JSON marker and
|
|
581
|
+
the bind must name that field (for example, `from: payload.value`).
|
|
485
582
|
|
|
486
583
|
### `work agent-run` — the only Step Agent dispatcher
|
|
487
584
|
|
|
@@ -1340,6 +1437,17 @@ usage errors before credential or network access. The command does not claim,
|
|
|
1340
1437
|
dispatch, close, or otherwise drive work—the standing Shift discovers the run
|
|
1341
1438
|
through its normal crew inbox.
|
|
1342
1439
|
|
|
1440
|
+
`--scope <label>` is forwarded as the run's `scope`: a free routing label
|
|
1441
|
+
recorded on the instance, with no registry and no fixed set of values. Omit it
|
|
1442
|
+
and the run carries no scope. `--priority <low|normal|high>` is forwarded as the
|
|
1443
|
+
run's `priority`; omit it and the hub applies `normal`. A value outside
|
|
1444
|
+
`low|normal|high` is a local usage error before any credential or network
|
|
1445
|
+
access, not a forwarded request. Like `--crew`/`--title`, a bare
|
|
1446
|
+
`--scope`/`--priority` or a `--scope=`/`--priority=` is a local usage error.
|
|
1447
|
+
Both are recorded at start only and are never writable afterwards. Do not
|
|
1448
|
+
confuse `--scope` (this routing label) with `--scopes` on `agent new`/`setup`,
|
|
1449
|
+
which lists an agent token's authorization scopes.
|
|
1450
|
+
|
|
1343
1451
|
### `cancel` — stop a running instance
|
|
1344
1452
|
|
|
1345
1453
|
`owenloop cancel <workflow>` sends `POST /api/cancel_run` and prints whether the
|
|
@@ -2402,7 +2510,7 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
|
|
|
2402
2510
|
|
|
2403
2511
|
## `setup` — onboard a machine
|
|
2404
2512
|
|
|
2405
|
-
`owenloop setup` is the one-shot onboarding command. It runs
|
|
2513
|
+
`owenloop setup` is the one-shot onboarding command. It runs eight ordered steps.
|
|
2406
2514
|
Depending on the machine state, setup may store the human credential, mint or
|
|
2407
2515
|
rekey and store a Scoped Identity credential, ensure the three principal
|
|
2408
2516
|
signing keys, relay a signed machine enrollment grant, and write only
|
|
@@ -2429,7 +2537,15 @@ plugin version already installed performs no plugin writes. The steps:
|
|
|
2429
2537
|
5. **execution settings** — write only `hubOrigin` into the execution settings
|
|
2430
2538
|
file so the local Step Agent talks to this hub, preserving every other key
|
|
2431
2539
|
(skipped when `hubOrigin` already matches).
|
|
2432
|
-
6. **
|
|
2540
|
+
6. **crew rosters** — for every crew known to the verified or newly minted
|
|
2541
|
+
Scoped Identity, materialize a local strongest-layer skeleton at its resolved
|
|
2542
|
+
`crews/<crew>.json` path. Each new file contains a descriptive `note`, its
|
|
2543
|
+
exact `crew` identity when needed by the bounded filename codec, and
|
|
2544
|
+
`"roster": {}`, so the machine initially inherits the weaker settings and
|
|
2545
|
+
hub layers. Setup never overwrites an existing acceptable crew-roster file:
|
|
2546
|
+
it reports that file as skipped and leaves its bytes untouched. If setup does
|
|
2547
|
+
not know any crews for the identity, it records a non-fatal noted result.
|
|
2548
|
+
7. **plugin** — probe and converge the bundled `owenloop` plugin separately
|
|
2433
2549
|
for Claude Code and Codex. When the installed plugin is missing or its
|
|
2434
2550
|
version differs from the CLI package, setup adds the bundled marketplace
|
|
2435
2551
|
when needed and installs or updates the plugin. Claude Code uses
|
|
@@ -2440,10 +2556,10 @@ plugin version already installed performs no plugin writes. The steps:
|
|
|
2440
2556
|
**Non-fatal:** a missing harness or failed convergence is reported as
|
|
2441
2557
|
`noted` and never fails setup. If the bundled marketplace root is
|
|
2442
2558
|
unavailable, setup prints manual commands instead.
|
|
2443
|
-
|
|
2559
|
+
8. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
|
|
2444
2560
|
the same surfaces, whose result becomes setup's exit code.
|
|
2445
2561
|
|
|
2446
|
-
Progress lines (the `[n/
|
|
2562
|
+
Progress lines (the `[n/8]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
2447
2563
|
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
2448
2564
|
**stdout**.
|
|
2449
2565
|
|
|
@@ -2733,7 +2849,7 @@ or set, not from inference.
|
|
|
2733
2849
|
|
|
2734
2850
|
### Tools
|
|
2735
2851
|
|
|
2736
|
-
The server exposes
|
|
2852
|
+
The server exposes 20 baseline tools mirroring the hub's own MCP toolset, plus
|
|
2737
2853
|
`create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
|
|
2738
2854
|
`add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
|
|
2739
2855
|
toolset. Each baseline tool's result is the hub REST response as one text
|
|
@@ -2741,11 +2857,12 @@ block; a non-2xx response comes back as an error result.
|
|
|
2741
2857
|
|
|
2742
2858
|
| tool | what it does |
|
|
2743
2859
|
|---|---|
|
|
2744
|
-
| `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
|
|
2860
|
+
| `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances; optional `serve_capabilities` accepts raw advertised keys |
|
|
2745
2861
|
| `submit` | submit a work order output |
|
|
2746
2862
|
| `reject_artifact` | send an upstream artifact back to its producer with a reason |
|
|
2863
|
+
| `retry_artifact` | re-arm a stalled or rejected artifact to owed — the human stall-clear, and the answer path for a worker's `ask` |
|
|
2747
2864
|
| `provide_input` | answer a human gate — provide a value for a seeded/owed input |
|
|
2748
|
-
| `start_run` | create a new instance from a definition name |
|
|
2865
|
+
| `start_run` | create a new instance from a definition name; optional `scope` (free routing label, defaults to the session's repo name) and `priority` (`low\|normal\|high`) |
|
|
2749
2866
|
| `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
|
|
2750
2867
|
| `get_workflow` | fetch one loaded definition |
|
|
2751
2868
|
| `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
|
|
@@ -2755,8 +2872,10 @@ block; a non-2xx response comes back as an error result.
|
|
|
2755
2872
|
| `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
|
|
2756
2873
|
| `publish_event` | publish an event against a contract, starting one run per matched subscription |
|
|
2757
2874
|
| `list_subscriptions` | the org's contract subscriptions |
|
|
2758
|
-
| `presence_ping` | register/refresh this Shift's presence — name, crews served (empty/omitted `serve_crews` means every crew this principal belongs to), and optionally which process incarnation is reporting (`shift_id`/`started_at`); observability only, a separate mechanism from the `heartbeat` lease tool above |
|
|
2875
|
+
| `presence_ping` | register/refresh this Shift's presence — name, crews served (empty/omitted `serve_crews` means every crew this principal belongs to), optional raw `serve_capabilities`, and optionally which process incarnation is reporting (`shift_id`/`started_at`); observability only, a separate mechanism from the `heartbeat` lease tool above |
|
|
2759
2876
|
| `list_shifts` | your principal's registered Shifts — online/offline derived at read time from last ping, crews served (returned as `crews`; empty means every crew this principal belongs to), and each one's reporting incarnation (`shiftId`/`startedAt`) when the hub recorded one |
|
|
2877
|
+
| `get_rosters` | read the org-global and per-crew capability rosters available to this principal |
|
|
2878
|
+
| `list_harness_models` | read the org's registered harnesses, models, and supported efforts |
|
|
2760
2879
|
| `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
|
|
2761
2880
|
| `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
|
|
2762
2881
|
| `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
|
|
@@ -2774,6 +2893,19 @@ message is surfaced verbatim; error bodies never carry tokens). If the store
|
|
|
2774
2893
|
write fails, the result says so and tells you to revoke/re-key the agent from
|
|
2775
2894
|
the console.
|
|
2776
2895
|
|
|
2896
|
+
`start_run`'s `scope` has one default the CLI does not have: when the caller
|
|
2897
|
+
supplies no `scope`, the server fills in the session's repository name, taken
|
|
2898
|
+
from the `origin` remote's URL (its last path segment, trailing `.git`
|
|
2899
|
+
removed) — `owenloop` for
|
|
2900
|
+
`https://github.com/typicalday/owenloop.git`. It is read from the remote rather
|
|
2901
|
+
than the directory name so that every worktree of one repo reports the same
|
|
2902
|
+
scope. It is a default, never an override: an explicitly supplied `scope` is
|
|
2903
|
+
always forwarded unchanged. When no repository name can be determined — not a
|
|
2904
|
+
git checkout, no `origin` remote, an unparseable URL — the server sends no
|
|
2905
|
+
`scope` at all rather than guessing a label. Two repositories with the same
|
|
2906
|
+
name under different owners therefore share a scope; pass an explicit `scope`
|
|
2907
|
+
to tell them apart.
|
|
2908
|
+
|
|
2777
2909
|
**The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
|
|
2778
2910
|
`remove_crew_member`) cover the same four operations as the [`crew` CLI
|
|
2779
2911
|
family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
|
|
@@ -2843,7 +2975,8 @@ interactively.
|
|
|
2843
2975
|
|
|
2844
2976
|
The [`examples/workflows`](../examples/workflows) folder has a workflow per
|
|
2845
2977
|
idea: [`delivery`](../examples/workflows/delivery.yaml) (a review knock-back
|
|
2846
|
-
loop
|
|
2978
|
+
loop — a teaching example, not the production line),
|
|
2979
|
+
[`ship`](../examples/workflows/ship.yaml) (delivery grown up: the full
|
|
2847
2980
|
production line with provisioned workspaces, an adversarial reviewer, a doc
|
|
2848
2981
|
pass, and teardown owned as a step),
|
|
2849
2982
|
[`research`](../examples/workflows/research.yaml) (collections),
|
|
@@ -2877,7 +3010,7 @@ wf=$(owenloop create delivery \
|
|
|
2877
3010
|
run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
|
|
2878
3011
|
owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
|
|
2879
3012
|
|
|
2880
|
-
owenloop status $wf #
|
|
3013
|
+
owenloop status $wf # done / debts / eligible / blocked / pending / inFlight
|
|
2881
3014
|
```
|
|
2882
3015
|
|
|
2883
3016
|
**A knock-back.** When the reviewer's job comes up, instead of greening its
|
|
@@ -2890,7 +3023,9 @@ owenloop reject $wf pr --by reviewer --text "tests are missing"
|
|
|
2890
3023
|
That re-arms `builder` with the reason attached to its next job. Do it past
|
|
2891
3024
|
`builder`'s `maxAttempts` and `pr` **stalls** — owenloop stops re-arming it
|
|
2892
3025
|
and waits for a human. `owenloop retry $wf pr --text "use the new fixture"`
|
|
2893
|
-
clears the stall and resets the counter.
|
|
3026
|
+
clears the stall and resets the counter. `retry --text` is also the answer
|
|
3027
|
+
path for a step that escalated with `ask`; pass `--hub <url>` to answer an
|
|
3028
|
+
ask on a hub-hosted run.
|
|
2894
3029
|
|
|
2895
3030
|
## `reap`, `runs`, and `status.inFlight` — observing and clearing in-flight work
|
|
2896
3031
|
|
|
@@ -2943,6 +3078,12 @@ refuses it. The result JSON is always written to stdout; the human-readable
|
|
|
2943
3078
|
reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
|
|
2944
3079
|
non-zero exit as a failure, not a success.
|
|
2945
3080
|
|
|
3081
|
+
For a bound modifier artifact, local `reject` also accepts
|
|
3082
|
+
`--requested <modifier>`. The engine checks that the requested value is one of
|
|
3083
|
+
the workflow's declared modifiers and carries it in the artifact's next reason
|
|
3084
|
+
thread, where a deterministic producer such as `util modifier-init` can read it.
|
|
3085
|
+
The flag is only valid for an artifact bound to `modifier`.
|
|
3086
|
+
|
|
2946
3087
|
## What a job looks like
|
|
2947
3088
|
|
|
2948
3089
|
`tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
|
|
@@ -2963,6 +3104,7 @@ them.
|
|
|
2963
3104
|
"inputs": ["plan"],
|
|
2964
3105
|
"outputs": ["pr"],
|
|
2965
3106
|
"worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
|
|
3107
|
+
"modifier": "standard", // modifier used for this offer; absent when unmodified
|
|
2966
3108
|
"consumes": { "plan": { /* the accepted input value */ } },
|
|
2967
3109
|
"owes": [ // the feedback channel
|
|
2968
3110
|
{ "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
|
|
@@ -2976,7 +3118,7 @@ A worker first **resolves the reference**: the `(defDigest, step, key)`
|
|
|
2976
3118
|
boundary maps the order to the exact authored instructions from the worker's
|
|
2977
3119
|
trusted local definition source — the same resolver the embedded engine and
|
|
2978
3120
|
the CLI use. Resolution returns the authored `prompt` (with
|
|
2979
|
-
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
|
|
3121
|
+
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}`
|
|
2980
3122
|
materialized), the authored `command` if the step has one, and nothing
|
|
2981
3123
|
fabricated. If the worker's source does not know the digest — the definition
|
|
2982
3124
|
was never delivered, or the current on-disk definition no longer matches the
|
package/docs/crypto.md
CHANGED
|
@@ -70,7 +70,7 @@ child stderr is never interpolated into error text.
|
|
|
70
70
|
| `machine` | the literal `"local"` |
|
|
71
71
|
| `agent` | the agent identity id |
|
|
72
72
|
|
|
73
|
-
`owenloop setup` step `[4/
|
|
73
|
+
`owenloop setup` step `[4/8] signing keys` ensures all three, in that order,
|
|
74
74
|
idempotently: a second run performs zero writes.
|
|
75
75
|
|
|
76
76
|
**One backend is selected once and never error-fallback.** A fallback after a
|
|
@@ -719,16 +719,32 @@ layout is:
|
|
|
719
719
|
```text
|
|
720
720
|
<config>/org-root.pub # public anchor, 0644
|
|
721
721
|
<config>/org-root # private anchor, 0600
|
|
722
|
-
<config>/
|
|
722
|
+
<config>/grants/<sha256hex(keyid)>.grant.dsse
|
|
723
723
|
<config>/revocations/<sha256hex(keyid)>.revocation.dsse
|
|
724
724
|
```
|
|
725
725
|
|
|
726
726
|
The root key is stored outside `PrincipalKeyManager` because the root is not a
|
|
727
727
|
hub-scoped principal key. The containing directory is `0700`; the private root
|
|
728
|
-
is never returned by the library or placed in an envelope. `
|
|
728
|
+
is never returned by the library or placed in an envelope. `loadGrants` and
|
|
729
729
|
`loadRevocations` return raw envelope bytes to the pure validator and refuse
|
|
730
730
|
symlinked or non-regular files.
|
|
731
731
|
|
|
732
|
+
If `<config>/grants` has zero `*.grant.dsse` entries while the pre-rename
|
|
733
|
+
`<config>/roster` is a readable, non-symlink directory of regular files that
|
|
734
|
+
holds grants, owenloop refuses rather than treating the machine as unenrolled.
|
|
735
|
+
It never reads or moves that legacy directory. When `<config>/grants` is
|
|
736
|
+
absent, the shell-quoted remediation is structurally
|
|
737
|
+
`mv <config>/roster <config>/grants`; this whole-directory rename preserves
|
|
738
|
+
every accepted grant filename, including dot-prefixed names. When a grants path
|
|
739
|
+
already exists, the printed remediation is instead
|
|
740
|
+
`rmdir <config>/grants && mv <config>/roster <config>/grants`. It moves only if
|
|
741
|
+
that path is an empty real directory; otherwise `rmdir` fails without moving
|
|
742
|
+
anything, and the operator must inspect `<config>/grants` by hand before
|
|
743
|
+
retrying. In either case, restart running owenloop shift daemons after a
|
|
744
|
+
successful migration. If the legacy source is a file or symlink, cannot be
|
|
745
|
+
inspected, or contains a non-regular entry, owenloop prints no migration
|
|
746
|
+
command: repair the named source path by hand before retrying the migration.
|
|
747
|
+
|
|
732
748
|
## Admin-signed policy floors
|
|
733
749
|
|
|
734
750
|
A policy floor is an org-wide minimum for local enforcement. An org admin signs
|
package/docs/design.md
CHANGED
|
@@ -970,6 +970,13 @@ step's last owed submit is what closes it — so the reverse order made every
|
|
|
970
970
|
reject from a single-owed-path step undeliverable. What follows the reject
|
|
971
971
|
depends on the hub's own answer, in its `closed` field:
|
|
972
972
|
|
|
973
|
+
The payload reject's `text` starts with the script's reason. When the command
|
|
974
|
+
has a non-empty captured output tail, the worker appends a labeled
|
|
975
|
+
`--- command output (last N bytes) ---` section containing the last 4 KiB of
|
|
976
|
+
combined stdout-then-stderr output (lossy UTF-8, with trailing newlines
|
|
977
|
+
trimmed before counting bytes). An empty tail adds nothing, and the payload
|
|
978
|
+
marker line is retained. Judge rejects are not changed by this formatting.
|
|
979
|
+
|
|
973
980
|
- `closed: true` — the rejected path was one of this firing's consumed inputs,
|
|
974
981
|
so the hub closed the run `no_work`. The owed paths stay debts and the step
|
|
975
982
|
re-fires against the rebuilt input. No receipt is submitted: an artifact
|
|
@@ -1682,7 +1689,7 @@ addressed by digest.
|
|
|
1682
1689
|
record or throws the named refusal; `resolveOrder(order)` builds the
|
|
1683
1690
|
`{defDigest, step, key}` ref from an order and additionally materializes the
|
|
1684
1691
|
runtime placeholders in the resolved prompt — the same substitution
|
|
1685
|
-
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}` that
|
|
1692
|
+
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}` that
|
|
1686
1693
|
`buildOrder` used to inline, moved whole to resolution time (unknown
|
|
1687
1694
|
placeholders stay untouched; `MAX_ATTEMPTS` renders the `maxAttempts` metadata
|
|
1688
1695
|
from the resolved instruction record). Substitution
|
|
@@ -1846,3 +1853,65 @@ path still requires a pre-commit verifier and remains fail-closed when that
|
|
|
1846
1853
|
adapter is not provided. The ingestor and verifier are separate concerns:
|
|
1847
1854
|
ingestion makes the bundle's verified object available, while the verifier
|
|
1848
1855
|
decides whether the install may commit it.
|
|
1856
|
+
|
|
1857
|
+
## §31 Cleanup on cancellation (`onCancel:`)
|
|
1858
|
+
|
|
1859
|
+
The engine's step grammar has a declarative cleanup marker:
|
|
1860
|
+
|
|
1861
|
+
```yaml
|
|
1862
|
+
- name: deprovisioner
|
|
1863
|
+
consumes: [merge, workspace]
|
|
1864
|
+
onCancel:
|
|
1865
|
+
consumes: [workspace]
|
|
1866
|
+
```
|
|
1867
|
+
|
|
1868
|
+
This is deliberately a new step key rather than another `on:` token.
|
|
1869
|
+
|
|
1870
|
+
| Existing key | What it means | Why it is not cleanup-on-cancel |
|
|
1871
|
+
|---|---|---|
|
|
1872
|
+
| `terminal: true` | A step's green is a destructive completion. | It says nothing about run lifecycle. |
|
|
1873
|
+
| `effect.onInvalidate` | Routes an already-green artifact after its inputs move. | Cancellation is not an input move. |
|
|
1874
|
+
| `on:` | Pure in-run firing vocabulary. | It has no lifecycle signal or per-trigger consume payload. |
|
|
1875
|
+
| `idleAfter:` | Duration sidecar for `on: [idle]`. | It is unrelated to cancellation. |
|
|
1876
|
+
| `x:` | Opaque extension map. | It cannot validate this declaration or catch typos. |
|
|
1877
|
+
|
|
1878
|
+
Finally, `on:` is evaluated by the clock-free, state-pure
|
|
1879
|
+
`eligibleFirings(ArtifactMap, TimeFacts)`; cancellation is neither artifact
|
|
1880
|
+
state nor a time fact, and `WorkflowData` has no instance status. It therefore
|
|
1881
|
+
cannot be a scheduler trigger in this package.
|
|
1882
|
+
|
|
1883
|
+
`onCancel:` is a mapping with exactly one required key, `consumes:`, a list of
|
|
1884
|
+
strings that may be empty. Every entry must be a unique stem from the owning
|
|
1885
|
+
step's own plain consumes. Map and reduce consumes have no key binding on a
|
|
1886
|
+
one-time cancellation firing and are refused. The key is refused on `calls:`
|
|
1887
|
+
steps by that grammar's smaller key allowlist. `allGreen` and `idle`
|
|
1888
|
+
evaluators may declare `onCancel:` only with an empty list because they cannot
|
|
1889
|
+
declare normal consumes. `terminal: true` together with `onCancel:` remains
|
|
1890
|
+
legal deliberately: the engine does not infer an author's cleanup policy.
|
|
1891
|
+
|
|
1892
|
+
`onCancel:` is inert in the standalone engine. It does not affect
|
|
1893
|
+
`eligibleFirings`, `modelCheck`, the forward cascade, or done-ness. A host
|
|
1894
|
+
with no cancellation concept loads a definition carrying it with no behavior
|
|
1895
|
+
change.
|
|
1896
|
+
|
|
1897
|
+
The control plane contract is:
|
|
1898
|
+
|
|
1899
|
+
> **`onCancel:` contract.** When the control plane cancels a run of instance `W`:
|
|
1900
|
+
>
|
|
1901
|
+
> 1. Resolve `W`'s def — `WorkflowData.defSnapshot` when pinned (§28), otherwise by name.
|
|
1902
|
+
> 2. Select the cleanup steps: `cancelCleanupSteps(def)` (exported from `owenloop`), i.e. every
|
|
1903
|
+
> step where `step.onCancel !== undefined`, in def order.
|
|
1904
|
+
> 3. For each such step `S`: if **every** stem in `S.onCancel.consumes` is green, dispatch an
|
|
1905
|
+
> order for `S` whose inputs are exactly those stems and their values. If any is not green,
|
|
1906
|
+
> `S` is not dispatchable — record that and do not block cancellation on it.
|
|
1907
|
+
> 4. `assertServableInstance` (`packages/hub-core/src/serving.ts`) must admit an order on a
|
|
1908
|
+
> `cancelled` instance **only** when that order is for a step selected in step 2. Every other
|
|
1909
|
+
> step stays refused, exactly as today.
|
|
1910
|
+
> 5. A step with no `onCancel:` is never dispatched after cancel — today's behaviour, unchanged.
|
|
1911
|
+
> 6. **Recommended, and the follow-on run's call to confirm:** hold the cancelled instance out of
|
|
1912
|
+
> its final closed state until each dispatched cleanup step's produces settle (green, or
|
|
1913
|
+
> exhausted per that step's `maxAttempts`). Closing immediately would reproduce the original
|
|
1914
|
+
> defect in a slower form — the order exists but nothing waits for it.
|
|
1915
|
+
> 7. `onCancel:` is inert in the standalone engine. `eligibleFirings`, `modelCheck`, the forward
|
|
1916
|
+
> cascade, and done-ness do not read it. A host with no cancellation concept loads and runs a
|
|
1917
|
+
> def carrying it with no behaviour change.
|