owenloop 0.5.6 → 0.5.8
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 +30 -0
- package/README.md +3 -6
- package/dist/packages/work/src/agent/approvals.d.ts +53 -0
- package/dist/packages/work/src/agent/approvals.js +132 -0
- package/dist/packages/work/src/agent/brief.d.ts +12 -0
- package/dist/packages/work/src/agent/brief.js +51 -0
- package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
- package/dist/packages/work/src/agent/capability-model.js +94 -91
- package/dist/packages/work/src/agent/loop.d.ts +43 -25
- package/dist/packages/work/src/agent/loop.js +135 -50
- package/dist/packages/work/src/bundle/types.d.ts +3 -3
- package/dist/packages/work/src/exec/loop.js +37 -15
- package/dist/packages/work/src/harness/child-env.js +4 -5
- package/dist/packages/work/src/harness/claude.d.ts +4 -0
- package/dist/packages/work/src/harness/claude.js +72 -3
- package/dist/packages/work/src/harness/codex.d.ts +37 -1
- package/dist/packages/work/src/harness/codex.js +136 -18
- package/dist/packages/work/src/harness/contract.d.ts +54 -1
- package/dist/packages/work/src/harness/session-store.d.ts +127 -17
- package/dist/packages/work/src/harness/session-store.js +157 -60
- package/dist/packages/work/src/hub/client.d.ts +13 -1
- package/dist/packages/work/src/hub/client.js +3 -0
- package/dist/packages/work/src/hub/types.d.ts +104 -3
- package/dist/packages/work/src/main.js +1 -0
- package/dist/packages/work/src/roles/agent-run.js +52 -42
- package/dist/packages/work/src/roles/approvals.d.ts +76 -0
- package/dist/packages/work/src/roles/approvals.js +231 -0
- package/dist/packages/work/src/roles/sessions.d.ts +3 -2
- package/dist/packages/work/src/roles/sessions.js +9 -2
- package/dist/packages/work/src/roles/settings.js +1 -1
- package/dist/packages/work/src/settings/roster.d.ts +21 -0
- package/dist/packages/work/src/settings/roster.js +80 -0
- package/dist/packages/work/src/settings/settings.d.ts +12 -24
- package/dist/packages/work/src/settings/settings.js +17 -35
- package/dist/packages/work/src/shift/loop.d.ts +2 -0
- package/dist/packages/work/src/shift/loop.js +2 -0
- package/dist/packages/work/src/shift/runtime.js +17 -9
- package/dist/packages/work/src/shift/spawn.d.ts +10 -53
- package/dist/packages/work/src/shift/spawn.js +28 -60
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +8 -4
- package/dist/src/capabilities.d.ts +44 -0
- package/dist/src/capabilities.js +38 -0
- package/dist/src/cli.d.ts +1 -0
- package/dist/src/cli.js +460 -5
- package/dist/src/config-dir.d.ts +13 -18
- package/dist/src/config-dir.js +15 -23
- package/dist/src/credentials.d.ts +1 -1
- package/dist/src/credentials.js +1 -1
- package/dist/src/crypto/records.d.ts +3 -0
- package/dist/src/crypto/records.js +19 -0
- package/dist/src/crypto/trust-roots.d.ts +2 -2
- package/dist/src/crypto/trust-roots.js +2 -2
- package/dist/src/engine.d.ts +14 -0
- package/dist/src/engine.js +26 -14
- package/dist/src/global-config.d.ts +4 -7
- package/dist/src/global-config.js +4 -7
- package/dist/src/hub.d.ts +207 -5
- package/dist/src/hub.js +263 -3
- package/dist/src/index.d.ts +2 -2
- package/dist/src/index.js +1 -1
- package/dist/src/model.d.ts +37 -1
- package/dist/src/model.js +47 -1
- package/dist/src/schemas/index.d.ts +19 -0
- package/dist/src/schemas/order.v1.schema.json +15 -1
- package/dist/src/store/pre-commit-verifier.js +1 -1
- package/dist/src/types.d.ts +58 -4
- package/dist/src/work-settings.d.ts +2 -4
- package/dist/src/work-settings.js +2 -4
- package/docs/agent-runner.md +2 -2
- package/docs/bundles.md +3 -1
- package/docs/cli.md +295 -101
- package/docs/crypto.md +14 -14
- package/docs/routing.md +607 -0
- package/docs/shift-logs.md +22 -6
- 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/claude-code/plugin/skills/author/SKILL.md +1 -2
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
package/docs/cli.md
CHANGED
|
@@ -60,6 +60,11 @@ for the full breakdown.
|
|
|
60
60
|
| `capability bind <capability> <crew> [--hub <url>]` | add a crew to a workflow capability on the hub org — a capability may route to many crews (admin; human credential) — see [Capability routes](#capability-routes) |
|
|
61
61
|
| `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
|
|
62
62
|
| `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
|
|
63
|
+
| `routing alerts [--workflow <wf>] [--limit <n>] [--hub <url>]` | list the hub org's routing alerts — every hold, reroute, wait and fallback the hub recorded — see [Routing](#routing) |
|
|
64
|
+
| `routing show <workflow> [--hub <url>]` | print one **hub run's** routing: modifier, wait policy, alerts, resolution reports and escalations — see [Routing](#routing) |
|
|
65
|
+
| `routing rule list [--hub <url>]` | list the org's capability **reroute rules**, in the order the hub tries them — see [Routing](#routing) |
|
|
66
|
+
| `routing rule add <capability> <target> [--position <n>] [--hub <url>]` | add one reroute rule — offer `<capability>` as `<target>` when it has no live crew binding (admin; human credential) — see [Routing](#routing) |
|
|
67
|
+
| `routing rule rm <capability> <target> [--hub <url>]` | remove one reroute rule — see [Routing](#routing) |
|
|
63
68
|
| `crew list [--hub <url>]` | list the hub org's crews with their members (includes the orphan crew once one exists) — see [Crews](#crews) |
|
|
64
69
|
| `crew new <name> --kind personal\|shared [--owner <memberId>] [--hub <url>]` | create a crew on the hub org (admin, or own personal crew; human credential) — see [Crews](#crews) |
|
|
65
70
|
| `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
|
|
@@ -68,6 +73,7 @@ for the full breakdown.
|
|
|
68
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) |
|
|
69
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) |
|
|
70
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** and the provenance of every selected candidate layer |
|
|
71
77
|
| `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) |
|
|
72
78
|
| `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) |
|
|
73
79
|
| `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
|
|
@@ -171,17 +177,12 @@ but attendance is advisory and observability-only. Attendance never changes
|
|
|
171
177
|
routing, dispatch, or lease behavior.
|
|
172
178
|
|
|
173
179
|
<a id="config-dir"></a>
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
2. `$XDG_CONFIG_HOME/owenloop` when `XDG_CONFIG_HOME` is non-blank;
|
|
181
|
-
3. `$HOME/.config/owenloop`.
|
|
182
|
-
|
|
183
|
-
The same directory holds `credentials.json`, `allowed_signers`, `org-root.pub`,
|
|
184
|
-
`roster/`, and `revocations/`.
|
|
180
|
+
By default, the execution settings file is `$HOME/.owenloop/settings.json`.
|
|
181
|
+
For test or throwaway isolation, `OWENLOOP_CONFIG_DIR` may name an absolute
|
|
182
|
+
directory used verbatim; `XDG_CONFIG_HOME` is not consulted. In the paths below,
|
|
183
|
+
`<config>` means the resolved owenloop config directory. The same directory
|
|
184
|
+
holds `credentials.json`, `allowed_signers`, `org-root.pub`, `roster/`, and
|
|
185
|
+
`revocations/`.
|
|
185
186
|
|
|
186
187
|
### `shift start <crew...>`
|
|
187
188
|
|
|
@@ -253,102 +254,56 @@ directories an order is **allowed to name**. Neither derives from the other.
|
|
|
253
254
|
owenloop shift start build --work-root ~/code --work-root /srv/work
|
|
254
255
|
```
|
|
255
256
|
|
|
256
|
-
**
|
|
257
|
-
|
|
258
|
-
|
|
257
|
+
**Crew roster selection.** “Roster” in this section means the **crew
|
|
258
|
+
roster** for capability routing, not the unrelated trust roster of signed
|
|
259
|
+
enrollment grants in `~/.owenloop/roster/`. A selected roster candidate decides
|
|
260
|
+
the harness, model, and effort for an agent order. Its precedence is:
|
|
259
261
|
|
|
260
|
-
1.
|
|
261
|
-
2. `
|
|
262
|
-
|
|
263
|
-
3. the `harness:` field on the verified step definition;
|
|
262
|
+
1. the first available candidate in the first matching crew roster;
|
|
263
|
+
2. `owenloop work agent-run --harness` (a local debug override);
|
|
264
|
+
3. the verified step's `x.harness.id`;
|
|
264
265
|
4. the first registered adapter.
|
|
265
266
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
```bash
|
|
275
|
-
OWENLOOP_HARNESS=codex OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/codex/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/codex
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
Both shifts may serve the SAME crew. The hub does not route by harness — it
|
|
279
|
-
offers an order to any shift whose crew is bound to the order's capability, and
|
|
280
|
-
whichever shift claims it first runs it on its own adapter.
|
|
281
|
-
|
|
282
|
-
**A per-shift config directory is not optional when the adapters differ.** The
|
|
283
|
-
settings file resolves from the config directory (see above), and it carries
|
|
284
|
-
`capabilityModels` — a map of composed capability to `{model, effort}` whose
|
|
285
|
-
model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
|
|
286
|
-
adapters need different model ids for the same capability, so they need
|
|
287
|
-
different settings files, so they need different config directories. A shared
|
|
288
|
-
config directory would give both shifts one adapter's model ids, and the shift
|
|
289
|
-
holding the wrong adapter fails at the vendor API on its first order.
|
|
290
|
-
|
|
291
|
-
**Use `OWENLOOP_CONFIG_DIR` for this, not `XDG_CONFIG_HOME`.** Both resolve the
|
|
292
|
-
settings file, and `OWENLOOP_CONFIG_DIR` wins — but `XDG_CONFIG_HOME` is a
|
|
293
|
-
machine-wide contract that `gh`, `git`, `gcloud`, `npm`, and most of the rest of
|
|
294
|
-
a developer's toolchain also read, and a shift spreads its ENTIRE environment
|
|
295
|
-
into every worker it dispatches, which passes it on to every command step's
|
|
296
|
-
child process. Scoping a shift with `XDG_CONFIG_HOME` therefore relocates the
|
|
297
|
-
configuration of every tool the workflow's own scripts shell out to. Measured,
|
|
298
|
-
not theorized: on one delivery run this stranded `gh`'s stored credential, and
|
|
299
|
-
the workflow's merge gate spent its full 40-minute wall clock deferring on a CI
|
|
300
|
-
probe that could not authenticate, followed by four consecutive merge failures
|
|
301
|
-
reading `could not resolve a pull request handle for the branch`. Nothing was
|
|
302
|
-
wrong with either script. `OWENLOOP_CONFIG_DIR` scopes owenloop and only
|
|
303
|
-
owenloop.
|
|
304
|
-
|
|
305
|
-
`OWENLOOP_CONFIG_DIR` names the owenloop config directory ITSELF — the directory
|
|
306
|
-
that directly holds `settings.json`, `credentials.json`, and `allowed_signers`.
|
|
307
|
-
No `owenloop` path segment is appended to it, unlike the `XDG_CONFIG_HOME` rung.
|
|
308
|
-
It must be an ABSOLUTE path: a relative one would resolve against whatever
|
|
309
|
-
working directory a step happens to have, and `workdirFrom` gives every step its
|
|
310
|
-
own.
|
|
311
|
-
|
|
312
|
-
Give each shift its own `--state-dir` as well. The state directory holds the
|
|
313
|
-
control socket (`shift.sock`), and a second shift starting against a socket
|
|
314
|
-
another shift already owns is refused.
|
|
315
|
-
|
|
316
|
-
**`capabilityModels` — which model serves which capability.** The hub decides
|
|
317
|
-
WHAT grade of work an order is; it composes the step's capability with the run's
|
|
318
|
-
depth modifier and stamps the result on the order (`builder` at the `deep`
|
|
319
|
-
modifier becomes `builder:deep`). It never decides which model serves that
|
|
320
|
-
grade. That decision is local, and this map is where the operator makes it:
|
|
267
|
+
The shift passes its start crews to each agent worker internally. A named crew
|
|
268
|
+
uses `~/.owenloop/crews/<crew>.json` above the machine-global
|
|
269
|
+
`~/.owenloop/settings.json` `roster` key. Each capability row is atomic:
|
|
270
|
+
the stronger layer replaces the weaker candidate array, and candidates are
|
|
271
|
+
tried in listed order. A step's `x.harness.id` is a policy constraint: a row
|
|
272
|
+
whose candidates do not include it is released as
|
|
273
|
+
`incompatible-harness-policy`; no available candidate is
|
|
274
|
+
`unresolvable-capability`.
|
|
321
275
|
|
|
322
276
|
```json
|
|
323
277
|
{
|
|
324
|
-
"
|
|
325
|
-
"builder:deep":
|
|
326
|
-
|
|
327
|
-
|
|
278
|
+
"roster": {
|
|
279
|
+
"builder:deep": [
|
|
280
|
+
{ "harness": "claude-code", "model": "claude-opus-5", "effort": "xhigh" },
|
|
281
|
+
{ "harness": "codex", "model": "gpt-5.6-sol", "effort": "xhigh" }
|
|
282
|
+
],
|
|
283
|
+
"builder": [
|
|
284
|
+
{ "harness": "codex", "model": "gpt-5.6-terra", "effort": "high" }
|
|
285
|
+
]
|
|
328
286
|
}
|
|
329
287
|
}
|
|
330
288
|
```
|
|
331
289
|
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
`
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
capability rows: whatever `tierProfiles.strongest` pointed at becomes the
|
|
350
|
-
`{model, effort}` of your `:deep` rows, and whatever `standard` pointed at
|
|
351
|
-
becomes the bare rows.
|
|
290
|
+
The array form is required even with one candidate. There is no migration path:
|
|
291
|
+
the retired key is rejected at settings load. Exact composed capability lookup
|
|
292
|
+
runs across the order's whole capability list before bare-name lookup, so an
|
|
293
|
+
exact row is never shadowed by an earlier bare row.
|
|
294
|
+
|
|
295
|
+
`~/.owenloop/config.json` and `~/.owenloop/settings.json` intentionally
|
|
296
|
+
remain separate. The control-plane `config.json` carries `hub`, is written by
|
|
297
|
+
`owenloop login`, and is read by `owenloop mcp`. The execution-plane
|
|
298
|
+
`settings.json` carries `hubOrigin` and the machine-global crew roster, is
|
|
299
|
+
written by `owenloop setup`, and is read by `owenloop work`. They answer
|
|
300
|
+
different callers and neither reads the other.
|
|
301
|
+
|
|
302
|
+
`owenloop roster show [crew]` prints the merged roster, every candidate's
|
|
303
|
+
winning-layer provenance, and every layer inspected (including an absent crew
|
|
304
|
+
file). `owenloop doctor` adds one line for each present crew roster file,
|
|
305
|
+
showing its found/absent layers and registered versus missing candidate
|
|
306
|
+
harnesses.
|
|
352
307
|
|
|
353
308
|
A clean start or `--once` completion exits `0`. `owenloop shift --help` also
|
|
354
309
|
exits `0`. Runtime failures such as credential reads or socket/runtime setup
|
|
@@ -549,8 +504,7 @@ An absent `x.harness.tools` field preserves the adapter's default tool surface;
|
|
|
549
504
|
`tools: []` is an explicit empty allow-list. The two forms are not equivalent.
|
|
550
505
|
Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
|
|
551
506
|
`owenloop work lint` runs the same common and adapter checks, but runtime
|
|
552
|
-
preflight remains authoritative because `--harness`
|
|
553
|
-
select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
|
|
507
|
+
preflight remains authoritative because roster availability and `--harness` can select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
|
|
554
508
|
for the capability matrix and the born-bound Owenloop control-plane exception.
|
|
555
509
|
|
|
556
510
|
**Harness-session durability.** `agent-run` records the provider session in the
|
|
@@ -1354,7 +1308,7 @@ owenloop login --hub https://hub.example
|
|
|
1354
1308
|
owenloop connect --hub https://hub.example
|
|
1355
1309
|
owenloop push newhire-onboarding
|
|
1356
1310
|
OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
|
|
1357
|
-
|
|
1311
|
+
owenloop shift start openai --origin https://hub.example --as default
|
|
1358
1312
|
```
|
|
1359
1313
|
|
|
1360
1314
|
Starting another run does not repeat installation, publication, preparation,
|
|
@@ -1420,6 +1374,8 @@ Three properties come from the hub verb, not from this command:
|
|
|
1420
1374
|
`owenloop instance show <workflow>` sends `GET /api/status/:wf` and prints the
|
|
1421
1375
|
instance's state: `done`, the `debts` it still owes, the steps that are
|
|
1422
1376
|
`eligible` or `blocked`, the runs `inFlight`, and `defDrift`.
|
|
1377
|
+
It also prints the hub's liveness verdict as `instanceStatus` and `terminal`
|
|
1378
|
+
when the hub provides those fields.
|
|
1423
1379
|
|
|
1424
1380
|
It answers the question no other local command can: **why is this run not
|
|
1425
1381
|
moving?** Two of its fields are the entire diagnosis, and both are invisible
|
|
@@ -1433,6 +1389,13 @@ from the outside because each one looks exactly like an idle shift:
|
|
|
1433
1389
|
never offered to anyone. Present only when something is actually parked;
|
|
1434
1390
|
`getStatus` omits the field otherwise, and `instance show` omits it too rather
|
|
1435
1391
|
than printing `[]`, which would read as "asked, and the answer is none."
|
|
1392
|
+
- **`instanceStatus` and `terminal`** — the hub's liveness verdict. `terminal: true`
|
|
1393
|
+
means the instance will receive no further dispatch; failed and
|
|
1394
|
+
cancelled instances can therefore be terminal even when `done` is false.
|
|
1395
|
+
A terminal instance also writes an advisory to stderr, while the JSON state
|
|
1396
|
+
remains on stdout. These fields are omitted when an older hub does not send
|
|
1397
|
+
them; an explicit `terminal: false` is preserved as the hub's affirmative
|
|
1398
|
+
live answer.
|
|
1436
1399
|
|
|
1437
1400
|
Naming, because two obvious names were already taken by different commands:
|
|
1438
1401
|
|
|
@@ -1662,7 +1625,7 @@ credential above is verified and stored, `login` makes one more best-effort
|
|
|
1662
1625
|
write: it records the hub origin it just authenticated against in
|
|
1663
1626
|
`~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
|
|
1664
1627
|
secret, just the origin). This file is separate from both the credential store
|
|
1665
|
-
above and from `owenloop setup`'s `~/.
|
|
1628
|
+
above and from `owenloop setup`'s `~/.owenloop/settings.json`; its only
|
|
1666
1629
|
reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
|
|
1667
1630
|
which needs to know your hub without enumerating the credential store (the
|
|
1668
1631
|
Keychain and external-command backends can't be listed at all — see below). A
|
|
@@ -2065,6 +2028,237 @@ needs a translation step.
|
|
|
2065
2028
|
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
2066
2029
|
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
2067
2030
|
|
|
2031
|
+
## Routing
|
|
2032
|
+
|
|
2033
|
+
`owenloop routing` reads and edits the hub's **live routing** state — what the
|
|
2034
|
+
hub did when it tried to reach a crew, and the operator's standing instructions
|
|
2035
|
+
for what to do when it cannot. [Routing](routing.md) is the conceptual guide;
|
|
2036
|
+
this section is the command surface.
|
|
2037
|
+
|
|
2038
|
+
**Three different objects share the word "routing". They are not
|
|
2039
|
+
interchangeable:**
|
|
2040
|
+
|
|
2041
|
+
| object | what it is | where it lives | which command |
|
|
2042
|
+
|---|---|---|---|
|
|
2043
|
+
| **capability route** | a `(capability, crew)` **binding** — the row that grants a crew the right to be offered that capability's work | `capability_routes` on the hub org | [`capability bind`/`unbind`/`list`](#capability-routes) |
|
|
2044
|
+
| **capability reroute rule** | an ordered operator statement — "when `<capability>` has no live crew binding, offer it as `<target>` instead" | `capability_reroutes` on the hub org | `routing rule list`/`add`/`rm` |
|
|
2045
|
+
| **routing alert** | an immutable **event row** the hub wrote when it held, rerouted, waited or fell back | `routing_alerts` on the hub org | `routing alerts`, and `routing show` for one run |
|
|
2046
|
+
|
|
2047
|
+
**A reroute rule is not a binding.** It names no crew, grants nobody access, and
|
|
2048
|
+
has no live/dangling distinction. It only says which *other capability name* the
|
|
2049
|
+
hub may substitute — and the substitution only reaches a crew if that target
|
|
2050
|
+
capability has a live binding of its own. Adding a reroute rule can therefore
|
|
2051
|
+
never widen who may claim work by itself; the widening, if any, already exists in
|
|
2052
|
+
`capability_routes`.
|
|
2053
|
+
|
|
2054
|
+
**A `binding-gap` alert means the hub HELD an offer** because its compound
|
|
2055
|
+
capability (`<capability>:<modifier>`, e.g. `build:express`) had no live crew
|
|
2056
|
+
binding, and it found no usable reroute target either. Holding is the deliberate
|
|
2057
|
+
default — the hub no longer silently falls back to the bare capability name — so
|
|
2058
|
+
these alerts are the record of work that is waiting rather than work that ran on
|
|
2059
|
+
the wrong grade. See [Routing §9b](routing.md#9b-the-new-rule-what-is-being-built).
|
|
2060
|
+
|
|
2061
|
+
### `routing alerts`
|
|
2062
|
+
|
|
2063
|
+
`GET /api/routing_alerts`, authenticated as your **human** credential. Lists the
|
|
2064
|
+
org's routing alerts. An org that has never held, rerouted, waited or fallen
|
|
2065
|
+
back is a normal success (exit 0) with an empty `alerts` array.
|
|
2066
|
+
|
|
2067
|
+
**The array order is the hub's answer and is never re-sorted here, and the two
|
|
2068
|
+
orderings are different:**
|
|
2069
|
+
|
|
2070
|
+
- **No `--workflow`** — an org-wide inbox, **newest first**. This is the "what is
|
|
2071
|
+
wrong right now" view.
|
|
2072
|
+
- **`--workflow <wf>`** — one run's alerts, **oldest first**. This is a
|
|
2073
|
+
chronological timeline: hold, then wait, then reroute, in the order the hub
|
|
2074
|
+
decided them.
|
|
2075
|
+
|
|
2076
|
+
Passing `--workflow` is what flips the ordering, so a script that pages through
|
|
2077
|
+
both must not assume one direction. The value is echoed back on stdout as
|
|
2078
|
+
`workflow` precisely so a reader can tell the two views apart without
|
|
2079
|
+
re-inspecting argv.
|
|
2080
|
+
|
|
2081
|
+
`--limit <n>` caps how many rows the hub returns. Omit it and the hub applies
|
|
2082
|
+
its own default page size. The hub **silently ignores** a limit it cannot use (a
|
|
2083
|
+
non-integer, zero, or a negative) and answers with its default instead — so the
|
|
2084
|
+
CLI rejects a `--limit` that is not a number **before** any request, rather than
|
|
2085
|
+
reporting a page size you never asked for.
|
|
2086
|
+
|
|
2087
|
+
A row's `modifier`, `step` and `detail` are legitimately `null` — an org-level
|
|
2088
|
+
event carrying no step or no modifier is a real state, not a defect — and they
|
|
2089
|
+
are printed as `null` rather than dropped. `detail` is an opaque per-kind
|
|
2090
|
+
metadata string the CLI forwards verbatim and never parses.
|
|
2091
|
+
|
|
2092
|
+
### `routing show <workflow>`
|
|
2093
|
+
|
|
2094
|
+
`GET /api/run_routing/<workflow>`, authenticated as your **human** credential.
|
|
2095
|
+
Prints the complete routing picture for ONE hub run: its modifier, its wait
|
|
2096
|
+
policy, its own alerts, its resolution reports (which rule matched for each step)
|
|
2097
|
+
and its escalations.
|
|
2098
|
+
|
|
2099
|
+
**This is not the local `show` command.** `owenloop show <wf>` dumps the raw
|
|
2100
|
+
artifacts of a **local** instance out of the local sqlite database and never
|
|
2101
|
+
touches a hub. `owenloop routing show <workflow>` takes a **hub** workflow id and
|
|
2102
|
+
reads hub state. They share four letters and nothing else.
|
|
2103
|
+
|
|
2104
|
+
`modifier` is **omitted entirely** for a run started without one. The key's
|
|
2105
|
+
absence is how stdout says "no modifier" — an empty string is never printed,
|
|
2106
|
+
because a modifier named nothing is not a state the hub can hold.
|
|
2107
|
+
|
|
2108
|
+
**An unknown or foreign workflow id gets a generic error today.** The hub's verb
|
|
2109
|
+
raises an untyped error for a run this org does not own or that does not exist,
|
|
2110
|
+
and its edge maps that to `HTTP 500` with the message `internal server error`.
|
|
2111
|
+
The CLI prints whatever message the hub sends, so a future typed `404` will
|
|
2112
|
+
surface as a useful sentence with no change here — but do not read today's
|
|
2113
|
+
`internal server error` as a hub defect; it is what "no such run for you" looks
|
|
2114
|
+
like on this endpoint right now.
|
|
2115
|
+
|
|
2116
|
+
`resolutionReports` and `escalations` belong to adjacent subsystems. Their rows
|
|
2117
|
+
are checked to be objects and then forwarded **verbatim**, so a field added on
|
|
2118
|
+
the hub widens what this command prints instead of breaking it.
|
|
2119
|
+
|
|
2120
|
+
### `routing rule list`
|
|
2121
|
+
|
|
2122
|
+
`GET /api/capability_reroutes`, authenticated as your **human** credential. Lists
|
|
2123
|
+
the org's reroute rules. An org with no rules is a normal success (exit 0) with
|
|
2124
|
+
an empty `reroutes` array.
|
|
2125
|
+
|
|
2126
|
+
**The array order is semantic: it is the order the hub TRIES the substitutions
|
|
2127
|
+
in**, and it is never re-sorted here. Rows are grouped by source `capability` and
|
|
2128
|
+
ascending `position` within each group, so the first row for a capability is the
|
|
2129
|
+
first target the hub attempts. Re-sorting this list client-side — even
|
|
2130
|
+
alphabetically, even "for readability" — would misreport which substitution
|
|
2131
|
+
actually happens.
|
|
2132
|
+
|
|
2133
|
+
### `routing rule add <capability> <target>`
|
|
2134
|
+
|
|
2135
|
+
`POST /api/add_capability_reroute`, authenticated as your **human** credential;
|
|
2136
|
+
requires the **admin** role on the hub. Adds one ordered rule: when
|
|
2137
|
+
`<capability>` has no live crew binding, the hub may offer the work as
|
|
2138
|
+
`<target>` instead.
|
|
2139
|
+
|
|
2140
|
+
The CLI performs no client-side validation of either argument — the hub is the
|
|
2141
|
+
enforcement of record. It rejects a rule whose `capability` and `target` are
|
|
2142
|
+
equal (`400 capability_reroute_invalid`), and the CLI surfaces that message
|
|
2143
|
+
verbatim.
|
|
2144
|
+
|
|
2145
|
+
**`--position <n>` sets the rule's rank among the rules for that same
|
|
2146
|
+
`<capability>`,** counting from `0` — lower is tried first. **Omitting
|
|
2147
|
+
`--position` APPENDS** the rule after the source capability's existing rules. The
|
|
2148
|
+
flag is omitted from the request body entirely when you do not pass it; sending
|
|
2149
|
+
`0` would mean "try this first", which is a different instruction.
|
|
2150
|
+
|
|
2151
|
+
**Adding is idempotent per `(capability, target)` pair.** Re-adding a pair that
|
|
2152
|
+
already exists is a normal success — the hub answers `200` with `alreadyPresent:
|
|
2153
|
+
true` and changes nothing (the original row keeps its position and timestamp).
|
|
2154
|
+
`ruleCount` reports how many rules the source capability has after the write.
|
|
2155
|
+
|
|
2156
|
+
Chains are resolved **by the hub**, not by this CLI and not by the engine: if
|
|
2157
|
+
`a → b` and `b → c` both exist, the hub walks the chain and hands the engine one
|
|
2158
|
+
final substitution.
|
|
2159
|
+
|
|
2160
|
+
### `routing rule rm <capability> <target>`
|
|
2161
|
+
|
|
2162
|
+
`POST /api/remove_capability_reroute`, authenticated as your **human**
|
|
2163
|
+
credential; requires the **admin** role on the hub. Removes the ONE
|
|
2164
|
+
`(capability, target)` rule you name. `<target>` is **required**: a capability
|
|
2165
|
+
may have several reroute rules, so a capability-only removal would delete more
|
|
2166
|
+
than you asked for.
|
|
2167
|
+
|
|
2168
|
+
**`rm` is idempotent, and unlike `add` it cannot fail on a bad pair.** Removing a
|
|
2169
|
+
rule that is not there is a normal success — the hub answers `200` with
|
|
2170
|
+
`removed: false` rather than a `404` — and the CLI prints a full document plus a
|
|
2171
|
+
stderr line saying nothing was removed. A script can call `routing rule rm`
|
|
2172
|
+
unconditionally without first checking whether the rule exists.
|
|
2173
|
+
|
|
2174
|
+
**Removing the last rule for a capability makes it HOLD again.** `remainingTargets:
|
|
2175
|
+
[]` on stdout is that signal, and stderr says so in words: with no rule left, an
|
|
2176
|
+
offer for that capability with no live crew binding waits instead of
|
|
2177
|
+
substituting. Nothing is lost — the held work resumes as soon as a crew binds
|
|
2178
|
+
the capability or a rule is added back.
|
|
2179
|
+
|
|
2180
|
+
### Flags, hub resolution, output and exits
|
|
2181
|
+
|
|
2182
|
+
**Flags.** `--hub <url>` on every subcommand; `--workflow <wf>` and `--limit <n>`
|
|
2183
|
+
on `routing alerts`; `--position <n>` on `routing rule add` (plus the global
|
|
2184
|
+
`--db`/`--defs`). The allowlist is per top-level command, so `--position` on
|
|
2185
|
+
`routing alerts` is accepted and ignored rather than rejected — the same
|
|
2186
|
+
looseness `crew list` has with `--kind`.
|
|
2187
|
+
|
|
2188
|
+
**Which hub gets acted on (`--hub`).** Resolution is the same narrow ladder
|
|
2189
|
+
`capability bind` uses, and for the same reason — a reroute rule written against
|
|
2190
|
+
the wrong org moves in-flight work and is not undone by a retry:
|
|
2191
|
+
|
|
2192
|
+
1. `--hub <origin>` if given (normalized the same way as everywhere else).
|
|
2193
|
+
2. Otherwise the **one** hub your credential *file* stores — if exactly one is
|
|
2194
|
+
present, it's used.
|
|
2195
|
+
3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
|
|
2196
|
+
in to exactly one hub); when more than one hub is stored their origins are
|
|
2197
|
+
listed back so you can pick.
|
|
2198
|
+
|
|
2199
|
+
This does **not** fall back to `OWENLOOP_HUB` or the built-in default hub, and
|
|
2200
|
+
hub enumeration is **file-store only**: the keychain and the external-command
|
|
2201
|
+
backend cannot list their entries, so on such a machine step 2 cannot enumerate
|
|
2202
|
+
the store and you must pass `--hub`.
|
|
2203
|
+
|
|
2204
|
+
**Printed JSON.** stdout is exactly one whitelisted JSON document per
|
|
2205
|
+
invocation, built from named fields — never a raw hub body — so `| jq` always
|
|
2206
|
+
works. Human progress lines (the two `routing rule rm` warnings) go to stderr
|
|
2207
|
+
only.
|
|
2208
|
+
|
|
2209
|
+
| subcommand | stdout |
|
|
2210
|
+
|---|---|
|
|
2211
|
+
| `routing alerts` | `{ "ok": true, "hub": "<origin>", "workflow": "wf_1", "alerts": [ { "id": "ral_1", "at": 1738000000000, "workflow": "wf_1", "kind": "binding-gap", "capability": "build:express", "modifier": "express", "step": "builder", "detail": null } ] }` |
|
|
2212
|
+
| `routing show` | `{ "ok": true, "hub": "<origin>", "workflow": "wf_1", "defName": "delivery", "modifier": "express", "waitPolicy": { "wait": "forever" }, "alerts": [ … ], "resolutionReports": [ … ], "escalations": [ … ] }` |
|
|
2213
|
+
| `routing rule list` | `{ "ok": true, "hub": "<origin>", "reroutes": [ { "capability": "build:express", "target": "build:standard", "position": 0, "createdAt": 1738000000000 } ] }` |
|
|
2214
|
+
| `routing rule add` | `{ "ok": true, "hub": "<origin>", "capability": "build:express", "target": "build:standard", "position": 0, "alreadyPresent": false, "ruleCount": 2 }` |
|
|
2215
|
+
| `routing rule rm` | `{ "ok": true, "hub": "<origin>", "capability": "build:express", "target": "build:standard", "removed": true, "remainingTargets": ["build"] }` |
|
|
2216
|
+
|
|
2217
|
+
Every field carries the **hub's own name**, verbatim — the same words its audit
|
|
2218
|
+
log and the web console use — so correlating stdout against them never needs a
|
|
2219
|
+
translation step.
|
|
2220
|
+
|
|
2221
|
+
- `workflow` (`routing alerts`) — present **only** when you passed `--workflow`,
|
|
2222
|
+
so its presence alone means the list is scoped and oldest-first. An empty
|
|
2223
|
+
`--workflow ''` is rejected as a usage error rather than sent, because the hub
|
|
2224
|
+
treats an empty value as absent and would answer org-wide under a stdout
|
|
2225
|
+
claiming a filter.
|
|
2226
|
+
- `kind` (`routing alerts`, `routing show`) — the hub's own event name
|
|
2227
|
+
(`binding-gap`, `reroute`, and others). It is forwarded verbatim and
|
|
2228
|
+
deliberately **not** narrowed to a fixed set, so a kind the hub adds later
|
|
2229
|
+
prints rather than breaks the command.
|
|
2230
|
+
- `modifier` (`routing show`) — **absent**, not `null`, for a run started without
|
|
2231
|
+
a modifier. On an alert row the same field IS `null`-able, because an alert
|
|
2232
|
+
that concerns no modified capability is a real event.
|
|
2233
|
+
- `waitPolicy` (`routing show`) — `{ "wait": "forever" }`, or
|
|
2234
|
+
`{ "wait": "<duration>", "then": "fallback" }` for a timed policy. `then` is
|
|
2235
|
+
absent on the forever form.
|
|
2236
|
+
- `position` (`routing rule list`, `routing rule add`) — the rule's rank among
|
|
2237
|
+
the rules for the same source capability, from `0`; lower is tried first. On
|
|
2238
|
+
`routing rule add` it is the rank the **hub** stored, which is routinely one
|
|
2239
|
+
you never typed, because omitting `--position` appends.
|
|
2240
|
+
- `alreadyPresent` (`routing rule add`) — was this exact `(capability, target)`
|
|
2241
|
+
pair already a rule before the call? `false` means the call created it.
|
|
2242
|
+
- `ruleCount` (`routing rule add`) — how many reroute rules the source capability
|
|
2243
|
+
has after the write.
|
|
2244
|
+
- `removed` (`routing rule rm`) — did this call actually remove a rule? `false`
|
|
2245
|
+
is the tolerant "it was never there" case, not an error.
|
|
2246
|
+
- `remainingTargets` (`routing rule rm`) — the targets the capability can still
|
|
2247
|
+
be substituted with. `[]` means the capability now **HOLDS** whenever it has no
|
|
2248
|
+
live crew binding: `jq '.remainingTargets | length == 0'`.
|
|
2249
|
+
- `capability` and `target` are the values the **hub** echoed back, not your
|
|
2250
|
+
argv: if the hub normalized either, stdout tells the truth about what was
|
|
2251
|
+
stored.
|
|
2252
|
+
|
|
2253
|
+
**Exit codes.**
|
|
2254
|
+
|
|
2255
|
+
| code | meaning |
|
|
2256
|
+
|---|---|
|
|
2257
|
+
| `0` | the alerts, run routing or rules were listed; the rule was added (or was already present); the rule was removed (or was already absent) |
|
|
2258
|
+
| `1` | usage error (an unknown subcommand, a missing `<workflow>`/`<capability>`/`<target>`, a non-numeric `--limit`, an empty `--workflow`) or a runtime or hub error — a self-referential rule, a `403` for a non-admin, an unknown workflow (see `routing show` above), a malformed response, or a network timeout |
|
|
2259
|
+
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
2260
|
+
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
2261
|
+
|
|
2068
2262
|
## Crews
|
|
2069
2263
|
|
|
2070
2264
|
A **crew** is an org-scoped queue that agent work is stamped to. Every hub org
|
package/docs/crypto.md
CHANGED
|
@@ -523,16 +523,16 @@ sidecar is checked against the bundle digest and the local `allowed_signers`
|
|
|
523
523
|
trust root. Origin verification is separate: `verifyOrigin` returns `absent`
|
|
524
524
|
when the origin sidecar is missing, `verified` only after DSSE signature, schema,
|
|
525
525
|
signer-key, and bundle-digest checks pass, and `unverifiable` or `invalid` for
|
|
526
|
-
the corresponding failures. The trust-root path is `<config>/allowed_signers`,
|
|
527
|
-
`$
|
|
528
|
-
|
|
529
|
-
|
|
526
|
+
the corresponding failures. The trust-root path is `<config>/allowed_signers`,
|
|
527
|
+
where `<config>` is `$HOME/.owenloop` by default or the absolute
|
|
528
|
+
`OWENLOOP_CONFIG_DIR` override. `XDG_CONFIG_HOME` is not consulted. A missing
|
|
529
|
+
or malformed trust root produces the distinct
|
|
530
530
|
`unverifiable` verdict; a present signature that fails verification produces
|
|
531
531
|
`invalid`.
|
|
532
532
|
|
|
533
533
|
The execution and install policy is `defPolicy`, with built-in default `warn`.
|
|
534
|
-
Set `defPolicy` in the JSON settings file at
|
|
535
|
-
|
|
534
|
+
Set `defPolicy` in the JSON settings file at `$HOME/.owenloop/settings.json`,
|
|
535
|
+
for example:
|
|
536
536
|
|
|
537
537
|
```json
|
|
538
538
|
{
|
|
@@ -711,16 +711,16 @@ whole organization.
|
|
|
711
711
|
|
|
712
712
|
### Local anchor and envelope files
|
|
713
713
|
|
|
714
|
-
The optional filesystem loader derives paths from
|
|
715
|
-
`
|
|
716
|
-
|
|
717
|
-
|
|
714
|
+
The optional filesystem loader derives paths from the shared owenloop config
|
|
715
|
+
directory (`$HOME/.owenloop` by default, or the absolute
|
|
716
|
+
`OWENLOOP_CONFIG_DIR` override). `XDG_CONFIG_HOME` is not consulted. The local
|
|
717
|
+
layout is:
|
|
718
718
|
|
|
719
719
|
```text
|
|
720
|
-
<config>/
|
|
721
|
-
<config>/
|
|
722
|
-
<config>/
|
|
723
|
-
<config>/
|
|
720
|
+
<config>/org-root.pub # public anchor, 0644
|
|
721
|
+
<config>/org-root # private anchor, 0600
|
|
722
|
+
<config>/roster/<sha256hex(keyid)>.grant.dsse
|
|
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
|