owenloop 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +45 -0
- package/README.md +98 -25
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{add.d.ts → src/add.d.ts} +12 -40
- package/dist/{add.js → src/add.js} +11 -176
- package/dist/src/cli.d.ts +147 -0
- package/dist/{cli.js → src/cli.js} +1643 -353
- package/dist/src/credentials.d.ts +280 -0
- package/dist/src/credentials.js +697 -0
- package/dist/{defs.js → src/defs.js} +59 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +29 -20
- package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
- package/dist/{hub.js → src/hub.js} +531 -1
- package/dist/{index.d.ts → src/index.d.ts} +3 -1
- package/dist/{index.js → src/index.js} +2 -1
- package/dist/src/lock.d.ts +80 -0
- package/dist/src/lock.js +217 -0
- package/dist/src/mcp/serve.d.ts +85 -0
- package/dist/src/mcp/serve.js +702 -0
- package/dist/src/mcp/server.d.ts +132 -0
- package/dist/src/mcp/server.js +327 -0
- package/dist/{model.d.ts → src/model.d.ts} +59 -4
- package/dist/{model.js → src/model.js} +149 -22
- package/dist/{types.d.ts → src/types.d.ts} +66 -24
- package/dist/{util.d.ts → src/util.d.ts} +25 -0
- package/dist/{util.js → src/util.js} +26 -0
- package/dist/src/work-settings.d.ts +57 -0
- package/dist/src/work-settings.js +84 -0
- package/docs/authoring.md +102 -53
- package/docs/cli.md +883 -29
- package/docs/design.md +119 -45
- package/docs/embedding.md +39 -14
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- package/dist/cli.d.ts +0 -83
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /package/dist/{untar.js → src/untar.js} +0 -0
package/docs/cli.md
CHANGED
|
@@ -21,10 +21,22 @@ every command, as above. `--help` on any command (or bare `-h`/`help`)
|
|
|
21
21
|
prints this usage and exits 0 without doing any work.
|
|
22
22
|
|
|
23
23
|
Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
|
|
24
|
-
`--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
|
|
25
|
-
`--now` on `reap`) never take a following
|
|
26
|
-
positional or the next `--flag`, never
|
|
27
|
-
`--flag=value` (e.g. `--now=<ms>` on
|
|
24
|
+
`--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
|
|
25
|
+
`--strict-inputs`, and the bare `--now` on `reap`) never take a following
|
|
26
|
+
value — the next token is always a positional or the next `--flag`, never
|
|
27
|
+
consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>` on
|
|
28
|
+
`tick`) for flags that do take a value.
|
|
29
|
+
|
|
30
|
+
`owenloop check <def>` defaults to treating `seedOwed` inputs as provided
|
|
31
|
+
(`assumeProvided: true`), so a def whose only initial gate is an unprovided
|
|
32
|
+
seeded input no longer reports a false depth-0 `True deadlocks` and doesn't
|
|
33
|
+
exit nonzero for it. `--strict-inputs` opts back out to the previous
|
|
34
|
+
seedOwed-starts-owed behavior, and when that's the def's only blocker also
|
|
35
|
+
prints a one-line hint naming the responsible input(s). `--assume-provided`
|
|
36
|
+
is still accepted (never errors) but is now redundant with the default; if
|
|
37
|
+
both flags are passed, `--strict-inputs` wins. See
|
|
38
|
+
[`docs/design.md` §25](design.md#25-the-model-checker-owenloop-check--scope)
|
|
39
|
+
for the full breakdown.
|
|
28
40
|
|
|
29
41
|
## Commands
|
|
30
42
|
|
|
@@ -37,9 +49,23 @@ positional or the next `--flag`, never consumed as this flag's argument. Use
|
|
|
37
49
|
| `connect [--hub <url>] [--as <slot>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
|
|
38
50
|
| `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
|
|
39
51
|
| `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
|
|
52
|
+
| `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) |
|
|
53
|
+
| `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) |
|
|
54
|
+
| `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
|
|
55
|
+
| `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
|
|
56
|
+
| `crew list [--hub <url>]` | list the hub org's crews with their members (includes the orphan crew once one exists) — see [Crews](#crews) |
|
|
57
|
+
| `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) |
|
|
58
|
+
| `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
|
|
59
|
+
| `crew member add <crewId> <principalKind> <principalId> [--hub <url>]` | add a member or agent to a crew — see [Crews](#crews) |
|
|
60
|
+
| `crew member rm <crewId> <principalId> [--hub <url>]` | remove a principal from a crew — see [Crews](#crews) |
|
|
61
|
+
| `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>]` | onboard this machine: may store human and Scoped Identity credentials, write only execution-settings `hubOrigin`, and after probing print missing-plugin commands instead of installing the plugin — see [`setup`](#setup--onboard-a-machine) |
|
|
62
|
+
| `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
|
|
63
|
+
| `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) |
|
|
64
|
+
| `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) |
|
|
65
|
+
| `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
|
|
40
66
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
41
67
|
| `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
|
|
42
|
-
| `tick <wf> [--now=<ms>] [--shallow] [--
|
|
68
|
+
| `tick <wf> [--now=<ms>] [--shallow] [--capability <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--capability` claims steps without capabilities plus matching-capability steps — see below |
|
|
43
69
|
| `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
|
|
44
70
|
| `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
|
|
45
71
|
| `status <wf>` | derived view: `done`, `debts`, `eligible`, `blocked`, `inFlight` |
|
|
@@ -57,6 +83,166 @@ positional or the next `--flag`, never consumed as this flag's argument. Use
|
|
|
57
83
|
| `delete <wf>` | delete an instance and all its rows |
|
|
58
84
|
| `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
|
|
59
85
|
|
|
86
|
+
## `shift` — foreground daemon and client
|
|
87
|
+
|
|
88
|
+
`owenloop shift` is the public local dispatch surface. `shift start` runs the
|
|
89
|
+
self-driven dispatch loop as a foreground process and listens on
|
|
90
|
+
`<stateDir>/shift.sock`. Each client connection carries one JSON-line request
|
|
91
|
+
and one JSON-line response. The daemon keeps polling and dispatching while no
|
|
92
|
+
`shift next` client is attached.
|
|
93
|
+
|
|
94
|
+
The `shift start` positional argument is a **crew** name. The routing API calls
|
|
95
|
+
that field a **crew**: `serve_crews` contains the selected crew names. Passing
|
|
96
|
+
`--all` maps to an empty `serve_crews` list, which means all crews available to
|
|
97
|
+
the Scoped Identity. Do not treat `attended_at` as a liveness signal: every
|
|
98
|
+
accepted `shift next` records attendance and makes the next presence ping due,
|
|
99
|
+
but attendance is advisory and observability-only. Attendance never changes
|
|
100
|
+
routing, dispatch, or lease behavior.
|
|
101
|
+
|
|
102
|
+
The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
103
|
+
`XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
|
|
104
|
+
`$HOME/.config/owenloop/settings.json`.
|
|
105
|
+
|
|
106
|
+
### `shift start <crew...>`
|
|
107
|
+
|
|
108
|
+
```text
|
|
109
|
+
owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
|
|
110
|
+
[--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
|
|
111
|
+
[--cache-dir <p>] [--state-dir <p>]
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
At least one named crew is required unless `--all` is present. `--all` and
|
|
115
|
+
named crews are mutually exclusive. Duplicate named crews collapse to one
|
|
116
|
+
entry before routing. The daemon owns one socket at a time; a second start
|
|
117
|
+
against the same socket is refused. There is no detach mode. `--once` performs
|
|
118
|
+
one loop sweep and exits instead of keeping the foreground daemon running.
|
|
119
|
+
|
|
120
|
+
| option | default and behavior |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `--origin <url>` | use this hub origin; otherwise use `hubOrigin` from the execution settings file; there is no hub-origin fallback |
|
|
123
|
+
| `--as <account>` | use this Scoped Identity account; defaults to `default` |
|
|
124
|
+
| `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
|
|
125
|
+
| `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
|
|
126
|
+
| `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
|
|
127
|
+
| `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
|
|
128
|
+
| `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
|
|
129
|
+
| `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
|
|
130
|
+
| `--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 |
|
|
131
|
+
|
|
132
|
+
A clean start or `--once` completion exits `0`. `owenloop shift --help` also
|
|
133
|
+
exits `0`. Runtime failures such as credential reads or socket/runtime setup
|
|
134
|
+
exit `1`. Usage and
|
|
135
|
+
precondition failures — including no crew or `--all`, invalid flags, a missing
|
|
136
|
+
hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
|
|
137
|
+
daemon's normal lifecycle line is written to stdout when it stays running;
|
|
138
|
+
diagnostics go to stderr.
|
|
139
|
+
|
|
140
|
+
### `shift next [--wait <seconds>]`
|
|
141
|
+
|
|
142
|
+
```text
|
|
143
|
+
owenloop shift next [--wait <seconds>] [--state-dir <p>]
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`--wait` accepts a finite, non-negative number of seconds and defaults to `90`.
|
|
147
|
+
`--state-dir` selects the daemon socket. Only one `next` call may be parked at
|
|
148
|
+
a time. A second parked call returns this error and exits `1`:
|
|
149
|
+
|
|
150
|
+
```text
|
|
151
|
+
whats_next is already parked — one park at a time (cancel it or wait for it to return)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
When a `next` request is accepted, the daemon stamps `attended_at`. The call
|
|
155
|
+
returns promptly when an event is queued, the wait expires, or the shift
|
|
156
|
+
explicitly ends. A normal timeout exits `0` and prints the current capacity
|
|
157
|
+
object, for example `{ "cap": 3, "free": 3, "running": 0, "events": [] }`.
|
|
158
|
+
Successful responses use the same capacity shape and may include queued event
|
|
159
|
+
objects. For `dispatched`, `reaped`, and `failed`, `kind` is either `exec` or
|
|
160
|
+
`agent-run`:
|
|
161
|
+
|
|
162
|
+
- `dispatched`: `{ "type": "dispatched", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "pid": 123 }`
|
|
163
|
+
- `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
|
|
164
|
+
- `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
|
|
165
|
+
- `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
|
|
166
|
+
|
|
167
|
+
`gate` is a reserved protocol shape for a future local representation of a
|
|
168
|
+
pending hub gate. Production code does not construct live hub gate events yet;
|
|
169
|
+
the local FIFO test and drill scope are recorded in
|
|
170
|
+
[`packages/work/test/shift-walkthrough.manual.md`](../packages/work/test/shift-walkthrough.manual.md).
|
|
171
|
+
|
|
172
|
+
If no daemon is listening, `next` exits `1` and prints the exact start guidance:
|
|
173
|
+
|
|
174
|
+
```text
|
|
175
|
+
no shift daemon at <stateDir>/shift.sock — start one with: owenloop shift start <crew…>
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Invalid arguments exit `2`. Other client or daemon runtime failures exit `1`.
|
|
179
|
+
All successful client output is one JSON object on stdout; diagnostics are on
|
|
180
|
+
stderr.
|
|
181
|
+
|
|
182
|
+
### `shift status [--state-dir <path>]`
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
owenloop shift status [--state-dir <p>]
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
With a daemon, status exits `0` and prints:
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{ "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`attended_at` remains `null` until the first accepted `next` request. Without a
|
|
195
|
+
daemon, status is still a successful question: it exits `0` and prints
|
|
196
|
+
`{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
|
|
197
|
+
other client/runtime errors exit `1`.
|
|
198
|
+
|
|
199
|
+
### `shift end [--state-dir <path>]`
|
|
200
|
+
|
|
201
|
+
```text
|
|
202
|
+
owenloop shift end [--state-dir <p>]
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
An explicit end stops the loop, resolves an in-flight `next` with an `ended`
|
|
206
|
+
event, sends the final presence update with `attended_at` omitted so the hub
|
|
207
|
+
clears the attendance stamp, closes the socket, and prints
|
|
208
|
+
`{ "ok": true, "ended": true }` with exit `0`. Detached `exec` and `agent-run`
|
|
209
|
+
children remain alive to finish under their own leases. Signal shutdown (for
|
|
210
|
+
example, Ctrl-C) stops the daemon but does not synthesize the `ended` event or
|
|
211
|
+
perform the explicit attendance-clearing update.
|
|
212
|
+
|
|
213
|
+
If no daemon is listening, `end` exits `1` with the same start guidance as
|
|
214
|
+
`next`. Invalid arguments exit `2`; other client/runtime errors exit `1`.
|
|
215
|
+
|
|
216
|
+
## `work` — execution-side CLI companion
|
|
217
|
+
|
|
218
|
+
The execution-side commands ship in the same `owenloop` npm package and use the
|
|
219
|
+
same `owenloop` binary. Replace the old separate `owenwork` invocation directly:
|
|
220
|
+
|
|
221
|
+
```text
|
|
222
|
+
owenwork <subcommand> ... → owenloop work <subcommand> ...
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The transplanted subcommand names remain. The standing Shift daemon is
|
|
226
|
+
only the root `owenloop shift` command; `owenloop work` has no standing-daemon alias.
|
|
227
|
+
`hold --mcp` remains because the machine-attached hold mount still exists.
|
|
228
|
+
Run `owenloop work --help` for the full role-specific usage.
|
|
229
|
+
|
|
230
|
+
The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
231
|
+
`XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
|
|
232
|
+
`$HOME/.config/owenloop/settings.json`.
|
|
233
|
+
|
|
234
|
+
| subcommand | what it does |
|
|
235
|
+
|---|---|
|
|
236
|
+
| `hold --order <id> [options]` | hold an order with a heartbeating lease |
|
|
237
|
+
| `exec <order-id> [options]` | run a command order in a self-leasing loop |
|
|
238
|
+
| `agent-run <order-id> [options]` | host an agent order's Step Agent in a harness and self-leasing loop |
|
|
239
|
+
| `prepare <workflow> [--origin <url>]` | fetch, cache, and normalize step specs |
|
|
240
|
+
| `lint <workflow-name \| path>` | lint `x.harness` option bags in a workflow definition |
|
|
241
|
+
| `sessions [--all] [--json]` | list recorded harness sessions and how to reopen them |
|
|
242
|
+
| `release --session <id> [options]` | drain a session's held claims |
|
|
243
|
+
| `settings` | print the resolved execution settings file |
|
|
244
|
+
| `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
|
|
245
|
+
|
|
60
246
|
## `add` — installing shared workflow defs from GitHub
|
|
61
247
|
|
|
62
248
|
`owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
|
|
@@ -240,13 +426,13 @@ ref) surfaces as a 404 from the sha-resolve step.
|
|
|
240
426
|
**Trust model — what `add` does and does not protect.** Installing a package
|
|
241
427
|
executes nothing at install time: `add` only fetches, validates, and writes
|
|
242
428
|
YAML under the defs dir. But an installed def's steps *run* later, with
|
|
243
|
-
whatever privileges the host process and its dispatcher grant their
|
|
244
|
-
owenloop itself never executes a step body — `
|
|
245
|
-
|
|
429
|
+
whatever privileges the host process and its dispatcher grant their Step Agents.
|
|
430
|
+
owenloop itself never executes a step body — `executor:`/`command:` are opaque
|
|
431
|
+
fields it carries through untouched and never shells out (see [What owenloop is
|
|
246
432
|
not](../README.md#what-owenloop-is-not) and
|
|
247
|
-
[`docs/authoring.md`](authoring.md#
|
|
248
|
-
real risk surface is the
|
|
249
|
-
prompts and `command:` strings that ship in a package are handed to
|
|
433
|
+
[`docs/authoring.md`](authoring.md#executor--declaring-the-executor)) — so the
|
|
434
|
+
real risk surface is the Shift or Step Agent you point at these defs: the
|
|
435
|
+
prompts and `command:` strings that ship in a package are handed to Step Agents that
|
|
250
436
|
typically run with your full local privileges. **Install only sources you
|
|
251
437
|
trust.**
|
|
252
438
|
|
|
@@ -264,7 +450,7 @@ install *step* — staged all-or-nothing validation with an atomic swap, path
|
|
|
264
450
|
containment (including symlink-aware `bodyFile` checks), and archive resource
|
|
265
451
|
bounds — not the def *content* that later executes. `add` validates a def's
|
|
266
452
|
structure and contains its paths; it does not sandbox or sanitize what a step
|
|
267
|
-
body will do once a
|
|
453
|
+
body will do once a Step Agent runs it. That trust decision stays yours.
|
|
268
454
|
|
|
269
455
|
**Untrusted-archive safety.** `add` treats the fetched repo as untrusted and
|
|
270
456
|
refuses the whole install (nothing written) on any of these:
|
|
@@ -381,6 +567,29 @@ can read (only read) a stored credential through the same backend logic via the
|
|
|
381
567
|
package's exported `readStoredCredential` — see
|
|
382
568
|
[Embedding](embedding.md#whats-exported).
|
|
383
569
|
|
|
570
|
+
**Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
|
|
571
|
+
token, or a `login`/`logout` that stores or deletes a slot — is serialized by a
|
|
572
|
+
lockfile at `credentials.lock`, a sibling of `credentials.json` in the config
|
|
573
|
+
dir (created for the keychain backend too, since the race it closes is
|
|
574
|
+
backend-independent). The concern is a token-refresh race: two owenloop
|
|
575
|
+
processes hitting an expiring OAuth token at once would each POST a refresh and
|
|
576
|
+
each persist, and because refresh tokens rotate, the second write clobbers the
|
|
577
|
+
first with a token whose refresh link is already spent — silently killing the
|
|
578
|
+
credential. Under the lock a process re-reads the slot after acquiring it and,
|
|
579
|
+
if another process already refreshed, **adopts** that fresh token instead of
|
|
580
|
+
refreshing again — one network refresh, one write, no lost token. The lock
|
|
581
|
+
matters only for OAuth refresh and store/delete; read paths and the external-
|
|
582
|
+
command mode (which never writes the local store) do not take it. Staleness is
|
|
583
|
+
liveness-based: a lock held by a dead same-host process is reclaimed at once, an
|
|
584
|
+
unparseable or pid-less lockfile is reclaimed once older than the ~30s TTL, and
|
|
585
|
+
a lock held by a live process is never age-reclaimed. If the lock can't be
|
|
586
|
+
acquired within the wait budget the CLI fails loudly (`another owenloop process
|
|
587
|
+
is using the credential store … — timed out waiting after Ns`) rather than
|
|
588
|
+
refreshing unlocked. Three test knobs override the timings:
|
|
589
|
+
`OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000), `OWENLOOP_CRED_LOCK_STALE_MS`
|
|
590
|
+
(default 30000), and `OWENLOOP_CRED_LOCK_POLL_MS` (default 100). No token value
|
|
591
|
+
ever appears in the lockfile or the timeout message.
|
|
592
|
+
|
|
384
593
|
**Supplying the credential from your own tooling.** If your secrets live in a
|
|
385
594
|
secret manager, or you run on a host with no keychain, set
|
|
386
595
|
`OWENLOOP_CREDENTIAL_COMMAND` to a shell command line that prints a credential.
|
|
@@ -493,6 +702,651 @@ Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
|
|
|
493
702
|
device-code grant remain recorded follow-ups on the service, not gaps in the
|
|
494
703
|
CLI.
|
|
495
704
|
|
|
705
|
+
### `agent new` — mint an agent token into a slot
|
|
706
|
+
|
|
707
|
+
`owenloop agent new <name>` mints a new Scoped Identity on the hub (`POST
|
|
708
|
+
/api/mint_agent_token`, authenticated as your **human** credential) and stores
|
|
709
|
+
the returned `olp_` token in the local credential slot `agent:<name>` — the same
|
|
710
|
+
slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
|
|
711
|
+
to provision an agent token without pasting one by hand: the mint and the store
|
|
712
|
+
happen in one step, and you never handle the secret.
|
|
713
|
+
|
|
714
|
+
**The token is never printed.** The minted `olp_` token goes process → store
|
|
715
|
+
only — it never appears on stdout, stderr, in an error, or in a log (identity
|
|
716
|
+
model §6, "rule of gates"). The confirmation JSON is built from a whitelist of
|
|
717
|
+
**non-secret** fields only: `hub`, `name`, `slot`, `crews` (the resolved crew
|
|
718
|
+
names), `scopes` (the minted token's scopes — `["work"]` by default, or whatever
|
|
719
|
+
`--scopes`/`--shift` selected), `storage` (`keychain` | `file`), `agentId` (the
|
|
720
|
+
Scoped Identity's id), and `tokenId` (a revocation handle). To use the Scoped Identity afterwards,
|
|
721
|
+
pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
|
|
722
|
+
on the hub.
|
|
723
|
+
|
|
724
|
+
**Which hub gets minted on (`--hub`).** Resolution is deliberately narrow —
|
|
725
|
+
minting on the wrong org is not undone by a retry:
|
|
726
|
+
|
|
727
|
+
1. `--hub <origin>` if given (normalized the same way as everywhere else).
|
|
728
|
+
2. Otherwise the **one** hub your credential *file* stores — if exactly one is
|
|
729
|
+
present, it's used.
|
|
730
|
+
3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
|
|
731
|
+
in to exactly one hub); when more than one hub is stored their origins are
|
|
732
|
+
listed back so you can pick.
|
|
733
|
+
|
|
734
|
+
Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
|
|
735
|
+
built-in default hub — silently defaulting a mint would risk minting on the
|
|
736
|
+
production hub while you're logged into a dev one. Note that hub enumeration is
|
|
737
|
+
**file-store only** (shared with `owenloop mcp`): the keychain and the
|
|
738
|
+
external-command backend cannot list their entries, so on such a machine step 2
|
|
739
|
+
cannot enumerate the store and you must pass `--hub`.
|
|
740
|
+
|
|
741
|
+
**`--crews <a,b>`.** A comma-separated list of crew names the token is granted
|
|
742
|
+
on (trimmed, empties dropped). Omit the flag to let the hub default the token to
|
|
743
|
+
the minter's personal crew; `--crews ""` (or `--crews ,`) is a usage error. Crew
|
|
744
|
+
names are validated by the hub, not the client.
|
|
745
|
+
|
|
746
|
+
**`--scopes <a,b>` / `--shift`.** A comma-separated list of scopes the minted
|
|
747
|
+
token carries (trimmed, empties dropped). Omit both flags to mint **work-only**
|
|
748
|
+
(the default). `--shift` is shorthand for `--scopes work,run` — the identity
|
|
749
|
+
a service account needs to both serve and *start* runs. The two flags are
|
|
750
|
+
mutually exclusive (`--scopes … --shift` together is a usage error), and
|
|
751
|
+
`--scopes ""` (or `--scopes ,`) is a usage error. Scope names are validated by
|
|
752
|
+
the hub, not the client.
|
|
753
|
+
|
|
754
|
+
**A configured external credential command blocks the mint.** If
|
|
755
|
+
`OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
|
|
756
|
+
supplies credentials for the hub, so `agent new` refuses up front (it has
|
|
757
|
+
nowhere to write the minted token); unset the variable to use the local store.
|
|
758
|
+
This check, the name validation, the empty-`--crews` check, the empty-`--scopes`
|
|
759
|
+
check, and the `--scopes`/`--shift` mutual-exclusivity check all run
|
|
760
|
+
**before** any network call, so a refusal never mints a server-side token first
|
|
761
|
+
— a mint that then failed to store would burn the agent name permanently.
|
|
762
|
+
|
|
763
|
+
**Exit codes.**
|
|
764
|
+
|
|
765
|
+
| code | meaning |
|
|
766
|
+
|---|---|
|
|
767
|
+
| `0` | minted and stored |
|
|
768
|
+
| `1` | generic failure — invalid or already-taken name, crew/shape rejection, network timeout, or a token that minted but couldn't be stored |
|
|
769
|
+
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
770
|
+
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
771
|
+
|
|
772
|
+
## Capability routes
|
|
773
|
+
|
|
774
|
+
A **capability route** maps a workflow-def **capability** (a logical capability tag a
|
|
775
|
+
def author writes, like `gpu` or `repo-access`) to a **crew** on one hub org.
|
|
776
|
+
Def authors write capabilities; an org admin binds each capability to at least one crew.
|
|
777
|
+
That indirection is what keeps deployment facts out of portable defs — see
|
|
778
|
+
[`capabilities:`](authoring.md#capabilities--logical-capability-tags) in the authoring guide
|
|
779
|
+
for the step-side declaration.
|
|
780
|
+
|
|
781
|
+
**A route is one `(capability, crew)` PAIR, and a capability may bind MANY crews.** The
|
|
782
|
+
pair is the unit that is created and destroyed: `capability bind` adds one, `capability unbind` removes one, and `capability list` returns one row per pair — so a capability bound
|
|
783
|
+
to three crews appears as three rows. A **dangling route** is one whose crew
|
|
784
|
+
row was deleted; it survives in the table, routes nothing, and never widens
|
|
785
|
+
access. A capability with **zero live routes** is **parked**: its steps wait.
|
|
786
|
+
|
|
787
|
+
**Resolution is live.** `start_run` only *checks* that every capability a run's steps
|
|
788
|
+
use is currently bound — it stamps no crew for a capability-routed step. Every later
|
|
789
|
+
routing decision (which Shift is offered the step, and whether a claim is
|
|
790
|
+
allowed) re-reads the route table as it stands at that moment.
|
|
791
|
+
|
|
792
|
+
**These edits take effect on work already in flight.**
|
|
793
|
+
|
|
794
|
+
- **Adding.** Running `capability bind` on a capability that is **already bound** ADDS the
|
|
795
|
+
named crew — it never displaces a crew already bound. Adding widens who can
|
|
796
|
+
serve the capability, live at the next poll of every in-flight run using it. Re-adding
|
|
797
|
+
a pair that is already there is a normal success, not an error (`alreadyRouted:
|
|
798
|
+
true`).
|
|
799
|
+
- **Removing.** Running `capability unbind` removes exactly ONE pair. If the capability still
|
|
800
|
+
has other live routes, it simply routes to a narrower set and nothing pauses.
|
|
801
|
+
If the removal takes away the **last live** route, the capability is **parked**:
|
|
802
|
+
the in-flight steps that use it are offered to no Shift and accept no
|
|
803
|
+
claim — until it is bound again. Nothing is lost; the work resumes on re-bind.
|
|
804
|
+
`remainingCrewIds: []` on stdout is that signal, and stderr says so in words.
|
|
805
|
+
- **Retargeting is two acts, not one.** There is no retarget command: add the new
|
|
806
|
+
crew, then remove the old one. Each is separately audited on the hub, and in
|
|
807
|
+
between **BOTH** crews serve the capability. The CLI deliberately does not chain the
|
|
808
|
+
two for you — the intermediate state is a real state an operator may want to sit
|
|
809
|
+
in, and collapsing it would hide a widened access window.
|
|
810
|
+
|
|
811
|
+
A capability route is **not** the project↔hub binding `owenloop connect` writes to
|
|
812
|
+
`.owenloop/hub.json` — that one records which hub *this project directory*
|
|
813
|
+
publishes to; a capability route is an org-scoped capability→crew row on the hub.
|
|
814
|
+
|
|
815
|
+
### `capability bind <capability> <crew>`
|
|
816
|
+
|
|
817
|
+
`POST /api/add_capability_route`, authenticated as your **human** credential;
|
|
818
|
+
requires the **admin** role on the hub. ADDS the crew named `<crew>` to
|
|
819
|
+
`<capability>`'s routes. `<crew>` is a crew **name** — the hub resolves it to a crew
|
|
820
|
+
id; the CLI does no crew lookup and performs no client-side validation of either
|
|
821
|
+
argument (the hub is the enforcement of record).
|
|
822
|
+
|
|
823
|
+
**Adding is idempotent per pair.** Re-adding a `(capability, crew)` pair that is
|
|
824
|
+
already bound is a normal success — the hub answers `200` with `alreadyRouted:
|
|
825
|
+
true` and changes nothing (the original row keeps its creator and timestamp).
|
|
826
|
+
`routedCrewCount` reports how many **live** crews the capability binds after the write.
|
|
827
|
+
|
|
828
|
+
### `capability unbind <capability> <crew>`
|
|
829
|
+
|
|
830
|
+
`POST /api/remove_capability_route`, authenticated as your **human** credential;
|
|
831
|
+
requires the **admin** role on the hub. Removes the ONE `(capability, crew)` route
|
|
832
|
+
you name. `<crew>` is **required**: a capability may bind many crews, so a capability-only
|
|
833
|
+
removal would unbind more than you asked for.
|
|
834
|
+
|
|
835
|
+
`<crew>` accepts the crew's **name**, or its raw **`crew_id`**. The raw-id form
|
|
836
|
+
is the only way to remove a **dangling** route — one whose crew row was
|
|
837
|
+
deleted, so there is no name left to resolve. `capability list` shows such a row
|
|
838
|
+
with `crewName: null`; take its `crewId` from there.
|
|
839
|
+
|
|
840
|
+
**`rm` is idempotent.** Removing a pair that is **not** bound is a normal
|
|
841
|
+
success — the hub answers `200` with `removed: false` rather than a `404` — and
|
|
842
|
+
the CLI prints a full document plus a stderr line saying nothing was removed. A
|
|
843
|
+
script can call `capability unbind` unconditionally without branching on whether the
|
|
844
|
+
pair was bound. On that tolerant path `crewId` is `null`, because the argument
|
|
845
|
+
matched neither a live crew name nor one of the capability's own rows.
|
|
846
|
+
|
|
847
|
+
**Removing the last live route parks the capability**, and stderr says so. See
|
|
848
|
+
"These edits take effect on work already in flight" above.
|
|
849
|
+
|
|
850
|
+
### `capability list`
|
|
851
|
+
|
|
852
|
+
`GET /api/capability_routes`, authenticated as your **human** credential. Lists the
|
|
853
|
+
org's routes, ONE row per `(capability, crew)` pair ordered by capability then crew id —
|
|
854
|
+
so a capability bound to several crews appears as several rows. An org with no
|
|
855
|
+
routes yet is a normal success (exit 0) with an empty `routes` array.
|
|
856
|
+
|
|
857
|
+
A row whose `crewName` is `null` is a **dangling route**: the crew it names was
|
|
858
|
+
deleted. Such a row routes nothing and never widens access, and it is shown
|
|
859
|
+
rather than hidden precisely so you can clean it up — remove it with `capability unbind
|
|
860
|
+
<capability> <crewId>`.
|
|
861
|
+
|
|
862
|
+
**Flags.** `--hub <url>` only (plus the global `--db`/`--defs`).
|
|
863
|
+
|
|
864
|
+
**Which hub gets acted on (`--hub`).** Resolution is deliberately narrow — the
|
|
865
|
+
same stance `agent new` takes, because a route written against the wrong org
|
|
866
|
+
is not undone by a retry, and under live resolution it also moves in-flight
|
|
867
|
+
work:
|
|
868
|
+
|
|
869
|
+
1. `--hub <origin>` if given (normalized the same way as everywhere else).
|
|
870
|
+
2. Otherwise the **one** hub your credential *file* stores — if exactly one is
|
|
871
|
+
present, it's used.
|
|
872
|
+
3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
|
|
873
|
+
in to exactly one hub); when more than one hub is stored their origins are
|
|
874
|
+
listed back so you can pick.
|
|
875
|
+
|
|
876
|
+
This does **not** fall back to `OWENLOOP_HUB` or the built-in default hub. Note
|
|
877
|
+
that hub enumeration is **file-store only**: the keychain and the
|
|
878
|
+
external-command backend cannot list their entries, so on such a machine step 2
|
|
879
|
+
cannot enumerate the store and you must pass `--hub`.
|
|
880
|
+
|
|
881
|
+
**Printed JSON.** stdout is exactly one whitelisted JSON document per
|
|
882
|
+
invocation, built from named fields — never a raw hub body — so `| jq` always
|
|
883
|
+
works. Human progress lines (the two `capability unbind` warnings) go to stderr only.
|
|
884
|
+
|
|
885
|
+
| subcommand | stdout |
|
|
886
|
+
|---|---|
|
|
887
|
+
| `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyRouted": false, "routedCrewCount": 2 }` |
|
|
888
|
+
| `capability unbind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crewId": "crw_1", "removed": true, "remainingCrewIds": ["crw_2"] }` |
|
|
889
|
+
| `capability list` | `{ "ok": true, "hub": "<origin>", "routes": [ { "capability": "gpu", "crewId": "crw_1", "crewName": "ml-crew", "createdBy": "u_1", "createdAt": 1738000000000 } ] }` |
|
|
890
|
+
|
|
891
|
+
Every added field carries the **hub's own name**, verbatim — the same words its
|
|
892
|
+
audit log and the web console use — so correlating stdout against them never
|
|
893
|
+
needs a translation step.
|
|
894
|
+
|
|
895
|
+
- `alreadyRouted` (`capability bind`) — was this exact `(capability, crew)` pair already
|
|
896
|
+
bound before the call? `false` means the pair was created by it.
|
|
897
|
+
- `routedCrewCount` (`capability bind`) — how many **live** crews the capability binds
|
|
898
|
+
after the write. A dangling route routes nothing and is not counted.
|
|
899
|
+
- `removed` (`capability unbind`) — did this call actually remove a pair? `false` is the
|
|
900
|
+
tolerant "it was never bound" case, not an error.
|
|
901
|
+
- `remainingCrewIds` (`capability unbind`) — the **live** crews the capability still binds.
|
|
902
|
+
`[]` means the capability is now **parked**: `jq '.remainingCrewIds | length == 0'`.
|
|
903
|
+
It can be `[]` while a dangling row survives, because such a row routes nothing.
|
|
904
|
+
- `crewId` (`capability unbind`) — the crew the hub resolved your `<crew>` argument to.
|
|
905
|
+
It is `null` on the tolerant `removed: false` path, where the argument matched
|
|
906
|
+
neither a live crew name nor one of the capability's own route rows. `capability unbind`
|
|
907
|
+
never prints a crew *name*: `remove_capability_route` does not return one, and
|
|
908
|
+
inventing one from argv would not be the hub's answer.
|
|
909
|
+
- `capability` and `crew` (`capability bind`) are the values the **hub** echoed back, not
|
|
910
|
+
your argv: if the hub normalized either, stdout tells the truth about what was
|
|
911
|
+
stored.
|
|
912
|
+
|
|
913
|
+
**Exit codes.**
|
|
914
|
+
|
|
915
|
+
| code | meaning |
|
|
916
|
+
|---|---|
|
|
917
|
+
| `0` | the crew was added to the capability (or was already bound), the route was removed (or was already absent), or the routes were listed |
|
|
918
|
+
| `1` | runtime or hub error — an unknown crew name (`capability bind` only; `capability unbind` answers a tolerant `removed: false` instead), a capability that fails the hub's name rules, a `403` for a non-admin, a malformed response, or a network timeout |
|
|
919
|
+
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
920
|
+
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
921
|
+
|
|
922
|
+
## Crews
|
|
923
|
+
|
|
924
|
+
A **crew** is an org-scoped queue that agent work is stamped to. Every hub org
|
|
925
|
+
can have, in addition to any crews an admin creates, one **orphan crew** (name
|
|
926
|
+
`orphan:unrouted`, `kind: "orphan"`) that the hub itself owns as the landing
|
|
927
|
+
zone for work whose crew was deleted out from under it. It is materialized
|
|
928
|
+
**lazily**, the first time a crew holding stamped work is deleted — an org
|
|
929
|
+
that has never deleted a crew with stamped work has no orphan crew at all, and
|
|
930
|
+
`crew list` shows none. Once it exists, `crew list` includes it — it is
|
|
931
|
+
marked, never hidden, via a derived `orphan: true` boolean on its row (see the
|
|
932
|
+
Printed JSON table below).
|
|
933
|
+
|
|
934
|
+
This family is independent of [capability routes](#capability-routes): a capability routes
|
|
935
|
+
to a crew by *name*, and a crew is where agent work actually queues. Deleting a
|
|
936
|
+
crew a capability still points at does not error — the capability's routing simply
|
|
937
|
+
resolves nowhere useful until it is rebound.
|
|
938
|
+
|
|
939
|
+
### `crew list`
|
|
940
|
+
|
|
941
|
+
`GET /api/crews`, authenticated as your **human** credential. Lists the org's
|
|
942
|
+
crews, each with its member rows (`principalKind`/`principalId`/`addedBy`/
|
|
943
|
+
`addedAt`). An org with no crews at all — including one that has never
|
|
944
|
+
materialized an orphan crew — is still a normal success (exit 0) with an empty
|
|
945
|
+
`crews` array.
|
|
946
|
+
|
|
947
|
+
### `crew new <name> --kind personal|shared [--owner <memberId>]`
|
|
948
|
+
|
|
949
|
+
`POST /api/create_crew`, authenticated as your **human** credential; requires
|
|
950
|
+
the **admin** role on the hub, **or** — for `--kind personal --owner
|
|
951
|
+
<memberId>` where `<memberId>` is the caller's own member id — no admin role
|
|
952
|
+
at all: a human may self-service additional personal crews for themself
|
|
953
|
+
without being an admin (`assertPoolMutationAllowed`, hub-core
|
|
954
|
+
`manage-crews.ts:211-214`). Every other combination (a `shared` crew, or a
|
|
955
|
+
`personal` crew owned by someone else) still requires admin. `--kind` is **required** but its value is
|
|
956
|
+
forwarded to the hub **verbatim and unvalidated** — the hub is the enforcement
|
|
957
|
+
of record for which kind values are legal (today `personal`/`shared`; `orphan`
|
|
958
|
+
is reserved for the hub's own crew). `--owner <memberId>` is optional and is
|
|
959
|
+
omitted from the request body entirely when not given — a `personal` crew
|
|
960
|
+
with no owner is the hub's own error to raise, not a client-side rule
|
|
961
|
+
duplicated here.
|
|
962
|
+
|
|
963
|
+
### `crew rm <crewId>`
|
|
964
|
+
|
|
965
|
+
`POST /api/delete_crew`, authenticated as your **human** credential; requires
|
|
966
|
+
the **admin** role on the hub for every crew kind, including a personal one —
|
|
967
|
+
`deletePool` bypasses the self-service gate that `crew new`/`crew member
|
|
968
|
+
add`/`crew member rm` use, and is admin-only unconditionally
|
|
969
|
+
(`manage-crews.ts:629`). Deletes the crew. The crew's **membership rows are
|
|
970
|
+
deleted outright, not moved** — `deleteAllPoolMembers` (`manage-crews.ts:706`)
|
|
971
|
+
runs unconditionally in the same transaction, whether or not any stamps
|
|
972
|
+
transfer; `membersRemoved` on stdout is a count of those deletions, since the
|
|
973
|
+
orphan crew's own membership is derived (always the org's current admins) and
|
|
974
|
+
cannot accept arbitrary members. Only the crew's **run stamps and
|
|
975
|
+
queued/running work** move to the org's orphan crew — memberships are never
|
|
976
|
+
among what moves.
|
|
977
|
+
|
|
978
|
+
**`rm` is idempotent.** Deleting a `<crewId>` that does not exist is a normal
|
|
979
|
+
success — the hub answers `200` with `deleted: false` rather than a `404` —
|
|
980
|
+
and the CLI prints this honestly (see below), plus a stderr line naming the
|
|
981
|
+
crew id, rather than inventing an error.
|
|
982
|
+
|
|
983
|
+
**Like [`capability unbind`](#capability-unbind-capability-crew), `crew rm` prints its tolerant
|
|
984
|
+
boolean on stdout** — `deleted` here, `removed` there. Both families report
|
|
985
|
+
honestly whether the call actually changed anything, and both narrate the
|
|
986
|
+
no-op case on stderr, so a script can branch on the boolean and a human reading
|
|
987
|
+
the terminal is told in words.
|
|
988
|
+
|
|
989
|
+
**The transfer fields are present on stdout if and only if the wire sent
|
|
990
|
+
them** — `membersRemoved`, `orphanCrewId`, `orphanCrewName`,
|
|
991
|
+
`stampsTransferred`, `runsTransferred` (an array of run ids, not a count), and
|
|
992
|
+
`runningRunsTransferred` (the subset still running, also an array) are never
|
|
993
|
+
defaulted to `0`/`null`/`[]`. Their absence means nothing moved; their
|
|
994
|
+
presence means a transfer happened, and stderr also gets a one-line human
|
|
995
|
+
summary naming the destination crew.
|
|
996
|
+
|
|
997
|
+
### `crew member add <crewId> <principalKind> <principalId>`
|
|
998
|
+
|
|
999
|
+
`POST /api/add_crew_member` authenticated as your **human** credential;
|
|
1000
|
+
requires the **admin** role on the hub, **or** the owner of the personal crew
|
|
1001
|
+
being acted on (same self-service carve-out as `crew new`, gated on the
|
|
1002
|
+
fetched crew row rather than the raw request — `manage-crews.ts:300`). Adds
|
|
1003
|
+
`<principalId>` (a member id or an agent id) to the crew as a
|
|
1004
|
+
`<principalKind>` (`member` or `agent`) member. `<principalKind>` is forwarded
|
|
1005
|
+
verbatim and unvalidated, same stance as `--kind` on `crew new`.
|
|
1006
|
+
|
|
1007
|
+
**The hub refuses this outright against the org's orphan crew, for every
|
|
1008
|
+
caller — including an admin.** `assertNotOrphanPool` (`manage-crews.ts:307`)
|
|
1009
|
+
throws before the add ever reaches the membership table, and it is a `400`,
|
|
1010
|
+
never a `403`: the refusal is identity-independent (true for every caller, not
|
|
1011
|
+
a permissions question), so a `403` would wrongly point the caller at their
|
|
1012
|
+
own role. The orphan crew's membership is derived — always the org's current
|
|
1013
|
+
admins, reconciled automatically on every membership change — and cannot be
|
|
1014
|
+
edited directly.
|
|
1015
|
+
|
|
1016
|
+
### `crew member rm <crewId> <principalId>`
|
|
1017
|
+
|
|
1018
|
+
`POST /api/remove_crew_member`, authenticated as your **human** credential;
|
|
1019
|
+
requires the **admin** role on the hub, **or** the owner of the personal crew
|
|
1020
|
+
being acted on (`manage-crews.ts:356`). Removes `<principalId>` from the crew.
|
|
1021
|
+
|
|
1022
|
+
**`member rm` is idempotent**, mirroring `crew rm`: removing a principal that
|
|
1023
|
+
was never a member of `<crewId>` is a normal `200` with `removed: false`, never
|
|
1024
|
+
a `404`. The CLI prints `removed: false` on stdout and a stderr line naming
|
|
1025
|
+
the principal and crew, rather than treating it as an error.
|
|
1026
|
+
|
|
1027
|
+
**Same orphan-crew refusal as `crew member add`.** Targeting the orphan crew
|
|
1028
|
+
is a `400` here too (`assertNotOrphanPool`, `manage-crews.ts:363`), for every
|
|
1029
|
+
caller including an admin, and for the same reason: the membership is derived,
|
|
1030
|
+
not editable.
|
|
1031
|
+
|
|
1032
|
+
**Flags.** `--hub <url>` only (plus the global `--db`/`--defs`), except `crew
|
|
1033
|
+
new`, which also takes `--kind` (required) and `--owner` (optional).
|
|
1034
|
+
|
|
1035
|
+
**Which hub gets acted on (`--hub`).** Identical resolution to the capability-route family: `--hub` if given, else the one hub your credential file stores, else
|
|
1036
|
+
exit 2 naming both remedies (and, on a multi-hub machine, listing the stored
|
|
1037
|
+
origins). No fallback to `OWENLOOP_HUB`
|
|
1038
|
+
or the built-in default hub; hub enumeration is file-store only.
|
|
1039
|
+
|
|
1040
|
+
**Printed JSON.** stdout is exactly one whitelisted JSON document per
|
|
1041
|
+
invocation — never a raw hub body — so `| jq` always works. Human-facing
|
|
1042
|
+
lines (the tolerant-false notices, the transfer summary) go to stderr only.
|
|
1043
|
+
|
|
1044
|
+
| subcommand | stdout |
|
|
1045
|
+
|---|---|
|
|
1046
|
+
| `crew list` | `{ "ok": true, "hub": "<origin>", "crews": [ { "id": "crw_1", "name": "team-a", "kind": "shared", "ownerMemberId": null, "createdBy": "u_1", "createdAt": 1738000000000, "orphan": false, "members": [ { "principalKind": "member", "principalId": "u_2", "addedBy": "u_1", "addedAt": 1738000000000 } ] } ] }` |
|
|
1047
|
+
| `crew new` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "name": "team-a", "kind": "shared", "ownerMemberId": null }` |
|
|
1048
|
+
| `crew rm` (no transfer) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "deleted": true, "membersRemoved": 2 }` |
|
|
1049
|
+
| `crew rm` (with transfer) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "deleted": true, "membersRemoved": 2, "orphanCrewId": "crw_orphan", "orphanCrewName": "orphan:unrouted", "stampsTransferred": 5, "runsTransferred": ["run_1", "run_2"], "runningRunsTransferred": ["run_2"] }` |
|
|
1050
|
+
| `crew rm` (unknown id) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_bogus", "deleted": false }` |
|
|
1051
|
+
| `crew member add` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalKind": "member", "principalId": "u_2" }` |
|
|
1052
|
+
| `crew member rm` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalId": "u_2", "removed": true }` |
|
|
1053
|
+
|
|
1054
|
+
**Exit codes.**
|
|
1055
|
+
|
|
1056
|
+
| code | meaning |
|
|
1057
|
+
|---|---|
|
|
1058
|
+
| `0` | the crew/membership was listed, created, removed (or was already absent) |
|
|
1059
|
+
| `1` | runtime or hub error — an unknown crew id on a member add/rm, a crew with active work refusing deletion, a `403` for a non-admin, a malformed response, or a network timeout |
|
|
1060
|
+
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
1061
|
+
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
1062
|
+
|
|
1063
|
+
## `setup` — onboard a machine
|
|
1064
|
+
|
|
1065
|
+
`owenloop setup` is the one-shot onboarding command. It runs six ordered steps.
|
|
1066
|
+
Depending on the machine state, setup may store the human credential, mint or
|
|
1067
|
+
rekey and store a Scoped Identity credential, and write only `hubOrigin` in the
|
|
1068
|
+
execution settings file while preserving its other keys. The plugin step only
|
|
1069
|
+
probes whether the Claude Code plugin is installed; when the probe reports it
|
|
1070
|
+
missing, setup prints manual install commands but never runs those commands or
|
|
1071
|
+
installs the plugin. The steps:
|
|
1072
|
+
|
|
1073
|
+
1. **inspect** — read-only report of what's already present (human credential,
|
|
1074
|
+
execution settings, `claude` on PATH, agent slots). No writes.
|
|
1075
|
+
2. **human login** — verify the stored **human** credential, or run the same
|
|
1076
|
+
loopback-OAuth browser flow as `owenloop login` when none is present or it no
|
|
1077
|
+
longer verifies. This is the gate that makes step 3's mint/rekey legal.
|
|
1078
|
+
3. **agent** — find a local `agent:<name>` slot that verifies live against the
|
|
1079
|
+
hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
|
|
1080
|
+
(replace the credential of) an existing one. How the target is chosen is
|
|
1081
|
+
[below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
|
|
1082
|
+
4. **execution settings** — write only `hubOrigin` into the execution settings
|
|
1083
|
+
file so the local Step Agent talks to this hub, preserving every other key
|
|
1084
|
+
(skipped when `hubOrigin` already matches).
|
|
1085
|
+
5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
|
|
1086
|
+
**Non-fatal:** while the marketplace is unpublished this step only *prints*
|
|
1087
|
+
the manual install commands (`claude plugin marketplace add owenloop` then
|
|
1088
|
+
`claude plugin install owenloop@owenloop`); it never fails setup.
|
|
1089
|
+
6. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
|
|
1090
|
+
the same surfaces, whose result becomes setup's exit code.
|
|
1091
|
+
|
|
1092
|
+
Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
1093
|
+
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
1094
|
+
**stdout**.
|
|
1095
|
+
|
|
1096
|
+
### Choosing the Scoped Identity (Flow A vs Flow B)
|
|
1097
|
+
|
|
1098
|
+
When step 3 has to act (no reusable local agent slot), it decides *which* Scoped Identity
|
|
1099
|
+
to connect this machine to:
|
|
1100
|
+
|
|
1101
|
+
- **Flow A — fresh org (no Scoped Identities on the hub):** setup asks you to
|
|
1102
|
+
**name** the Scoped Identity, prefilled with a sanitized form of the machine hostname.
|
|
1103
|
+
The name is a suggestion — any label matching `[A-Za-z0-9][A-Za-z0-9._-]*`
|
|
1104
|
+
(1–64 chars) is accepted. It then **mints** that Scoped Identity.
|
|
1105
|
+
- **Flow B — org already has Scoped Identities (succession):** setup shows the existing
|
|
1106
|
+
Scoped Identities (each with its name, when it was **last active**, and its **crews**)
|
|
1107
|
+
and asks whether this is a *new* installation or one that *replaces* an
|
|
1108
|
+
existing Scoped Identity. Choosing **new** mints a fresh Scoped Identity; choosing **replace**
|
|
1109
|
+
**rekeys** the chosen Scoped Identity — which **revokes that Scoped Identity's current
|
|
1110
|
+
credential**, so if it is still running elsewhere it will be disconnected
|
|
1111
|
+
there.
|
|
1112
|
+
|
|
1113
|
+
**Non-interactive runs must pass a bypass flag.** When stdin is not a TTY (a
|
|
1114
|
+
scripted or piped run) and step 3 needs to act, setup will not block on a
|
|
1115
|
+
prompt — it errors unless you pre-decide with one of:
|
|
1116
|
+
|
|
1117
|
+
- `--new-agent <name>` — mint a new Scoped Identity named `<name>` (skips Flow A's name
|
|
1118
|
+
prompt and Flow B's succession prompt).
|
|
1119
|
+
- `--replace-agent <name>` — rekey the existing Scoped Identity named `<name>` (skips the
|
|
1120
|
+
succession prompt); errors if no such Scoped Identity exists on the hub.
|
|
1121
|
+
|
|
1122
|
+
The two flags are mutually exclusive. `--crews <a,b>` applies **only** to a mint
|
|
1123
|
+
(`--new-agent` or a fresh org); combining it with `--replace-agent` is a usage
|
|
1124
|
+
error, because rekeying preserves the Scoped Identity's existing crews (manage those in
|
|
1125
|
+
the console). `--scopes <a,b>` likewise applies **only** to a mint — it selects
|
|
1126
|
+
the minted token's scopes (default `work`); combining it with `--replace-agent`
|
|
1127
|
+
is a usage error, because rekeying preserves the Scoped Identity's existing scopes (mint a
|
|
1128
|
+
new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
|
|
1129
|
+
scopes out with `--scopes work,run`.
|
|
1130
|
+
|
|
1131
|
+
### Hub resolution differs from `agent new`
|
|
1132
|
+
|
|
1133
|
+
`setup` (and `doctor`) resolve the target hub like `agent new` with **one**
|
|
1134
|
+
deliberate difference: a brand-new machine with **no** stored hub falls back to
|
|
1135
|
+
the built-in **default hub** (printing a `targeting <hub>` notice to stderr)
|
|
1136
|
+
instead of exiting 2. That is safe here because the mint happens only *after*
|
|
1137
|
+
you sign in through that hub's own browser consent, and the target is printed
|
|
1138
|
+
first. Resolution order:
|
|
1139
|
+
|
|
1140
|
+
1. `--hub <origin>` if given.
|
|
1141
|
+
2. Otherwise the **one** hub your credential *file* stores, if exactly one is
|
|
1142
|
+
present.
|
|
1143
|
+
3. More than one stored hub → **exit 2**, listing them so you can pass `--hub`.
|
|
1144
|
+
4. Zero stored hubs (or a keychain/external backend that can't enumerate) →
|
|
1145
|
+
the **default hub**, with a printed notice.
|
|
1146
|
+
|
|
1147
|
+
### A configured external credential command blocks setup
|
|
1148
|
+
|
|
1149
|
+
If `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
|
|
1150
|
+
supplies this hub's credentials, so setup **refuses up front**, *before any
|
|
1151
|
+
browser opens*. Its human-login and agent-mint steps would write keys nobody
|
|
1152
|
+
reads; unset the variable to use `owenloop login` and the local store. (This is
|
|
1153
|
+
the same guard `agent new` applies, just moved ahead of the OAuth round-trip so
|
|
1154
|
+
the flagship command never opens a browser only to fail at the store.)
|
|
1155
|
+
|
|
1156
|
+
### After setup
|
|
1157
|
+
|
|
1158
|
+
If the connected agent account is anything other than `default`, setup prints a
|
|
1159
|
+
reminder to run `owenloop work` with `OWENLOOP_ACCOUNT=<name>` so the Step Agent
|
|
1160
|
+
reads the right slot.
|
|
1161
|
+
|
|
1162
|
+
**Exit codes.**
|
|
1163
|
+
|
|
1164
|
+
| code | meaning |
|
|
1165
|
+
|---|---|
|
|
1166
|
+
| `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
|
|
1167
|
+
| `1` | setup ran but doctor's core checks did not all pass |
|
|
1168
|
+
| non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage Scoped Identities), a named `--replace-agent` that doesn't exist, or a configured external credential command |
|
|
1169
|
+
|
|
1170
|
+
## `doctor` — check a machine's install
|
|
1171
|
+
|
|
1172
|
+
`owenloop doctor` is the **read-only** diagnostic behind setup's final step. It
|
|
1173
|
+
probes the same install surfaces and prints one `✓`/`✗` line per check to
|
|
1174
|
+
stderr, plus a `{ ok, hub, checks }` summary to stdout. It performs **no
|
|
1175
|
+
configuration writes** — no mint, rekey, slot create/delete, settings write, or
|
|
1176
|
+
browser. (The one unavoidable carve-out: verifying the human credential may
|
|
1177
|
+
rotate-and-persist an *expiring* human OAuth token, exactly as every authed
|
|
1178
|
+
command does — refreshing without persisting would strand the rotated refresh
|
|
1179
|
+
token and corrupt the install.)
|
|
1180
|
+
|
|
1181
|
+
The checks, in order:
|
|
1182
|
+
|
|
1183
|
+
| # | check | ✓ means | core |
|
|
1184
|
+
|---|---|---|---|
|
|
1185
|
+
| 1 | human credential | a human credential is stored for this hub | yes |
|
|
1186
|
+
| 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
|
|
1187
|
+
| 3 | agent slot | an `agent:<name>` credential is stored | yes |
|
|
1188
|
+
| 4 | agent plane | that agent credential verifies live against the hub | yes |
|
|
1189
|
+
| 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
|
|
1190
|
+
| 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
|
|
1191
|
+
|
|
1192
|
+
Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
|
|
1193
|
+
<origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
|
|
1194
|
+
machine with no working human credential still renders lines 3–6, degrading
|
|
1195
|
+
honestly rather than dropping them.
|
|
1196
|
+
|
|
1197
|
+
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. The
|
|
1198
|
+
plugin check (6) is *rendered* but does not affect the exit code while the
|
|
1199
|
+
marketplace is unpublished.
|
|
1200
|
+
|
|
1201
|
+
## `mcp` — stdio control-plane server for MCP hosts
|
|
1202
|
+
|
|
1203
|
+
`owenloop mcp` is a long-running server that exposes the hub's **human control
|
|
1204
|
+
plane** to a local MCP host (Claude Code, or any client that speaks MCP over
|
|
1205
|
+
stdio). This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
|
|
1206
|
+
subprocess — **you do not run it yourself at a prompt**. It reads
|
|
1207
|
+
newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
|
|
1208
|
+
authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
|
|
1209
|
+
JSON-RPC reply on stdout. It runs until stdin closes (EOF), then exits `0`.
|
|
1210
|
+
|
|
1211
|
+
It authenticates as the logged-in **human**, using the same stored credential
|
|
1212
|
+
`login` writes and the same locked OAuth-refresh path the other hub commands
|
|
1213
|
+
use. It is never interactive: it never opens a browser and never starts a
|
|
1214
|
+
loopback listener. If no human credential is stored, a tool call returns an
|
|
1215
|
+
error telling you to run `owenloop login --hub <origin>` in a terminal and retry
|
|
1216
|
+
(see [Authentication and secrets](#authentication-and-secrets) below).
|
|
1217
|
+
|
|
1218
|
+
### Choosing the hub origin
|
|
1219
|
+
|
|
1220
|
+
`owenloop mcp` binds to exactly one hub origin, resolved in this order:
|
|
1221
|
+
|
|
1222
|
+
1. `--hub <url>` flag.
|
|
1223
|
+
2. `OWENLOOP_HUB` env var.
|
|
1224
|
+
3. If the **file** credential backend holds exactly ONE hub with a valid `human`
|
|
1225
|
+
credential, that hub is used.
|
|
1226
|
+
4. Otherwise it exits `2` and prints why to stderr (nothing is written to
|
|
1227
|
+
stdout — stdout is the protocol channel).
|
|
1228
|
+
|
|
1229
|
+
There is **no** silent default-hub fallback: a control-plane server must never
|
|
1230
|
+
bind to a hub you did not name. The exit-`2` messages name both remedies:
|
|
1231
|
+
|
|
1232
|
+
- No hub credentials stored → `run \`owenloop login --hub <origin>\` first, or pass --hub <origin>`.
|
|
1233
|
+
- More than one hub stored → the message lists every stored origin and says `pass --hub <origin>`.
|
|
1234
|
+
- The credential store cannot be enumerated (macOS Keychain or an external
|
|
1235
|
+
credential command) → `pass --hub <origin> (or set OWENLOOP_HUB)`. Only the
|
|
1236
|
+
file backend can list stored origins, so on a Keychain-backed machine `mcp`
|
|
1237
|
+
effectively requires `--hub` or `OWENLOOP_HUB`.
|
|
1238
|
+
|
|
1239
|
+
A malformed `--hub`/`OWENLOOP_HUB` value is a normal exit-`1` error, like every
|
|
1240
|
+
other command.
|
|
1241
|
+
|
|
1242
|
+
### Tools
|
|
1243
|
+
|
|
1244
|
+
The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
|
|
1245
|
+
`create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
|
|
1246
|
+
`add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
|
|
1247
|
+
toolset. Each baseline tool's result is the hub REST response as one text
|
|
1248
|
+
block; a non-2xx response comes back as an error result.
|
|
1249
|
+
|
|
1250
|
+
| tool | what it does |
|
|
1251
|
+
|---|---|
|
|
1252
|
+
| `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
|
|
1253
|
+
| `submit` | submit a work order output |
|
|
1254
|
+
| `reject_artifact` | send an upstream artifact back to its producer with a reason |
|
|
1255
|
+
| `provide_input` | answer a human gate — provide a value for a seeded/owed input |
|
|
1256
|
+
| `start_run` | create a new instance from a definition name |
|
|
1257
|
+
| `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
|
|
1258
|
+
| `get_workflow` | fetch one loaded definition |
|
|
1259
|
+
| `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
|
|
1260
|
+
| `get_status` | `engine.status` verbatim plus a plain-English rendering |
|
|
1261
|
+
| `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
|
|
1262
|
+
| `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
|
|
1263
|
+
| `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
|
|
1264
|
+
| `publish_event` | publish an event against a contract, starting one run per matched subscription |
|
|
1265
|
+
| `list_subscriptions` | the org's contract subscriptions |
|
|
1266
|
+
| `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 |
|
|
1267
|
+
| `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 |
|
|
1268
|
+
| `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
|
|
1269
|
+
| `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
|
|
1270
|
+
| `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
|
|
1271
|
+
| `create_crew` | create a crew (`name`, `kind`, optional `ownerMemberId`) |
|
|
1272
|
+
| `add_crew_member` | add a member or agent principal to a crew |
|
|
1273
|
+
| `remove_crew_member` | remove a principal from a crew (tolerant: removing a non-member is a normal result, not an error) |
|
|
1274
|
+
|
|
1275
|
+
`create_agent {name, crews?, scopes?}` mints a fresh Scoped Identity on the hub
|
|
1276
|
+
with `work` scope by default; pass `scopes` (e.g. `["work","run"]`) to choose the
|
|
1277
|
+
minted token's scopes. It then writes the minted `olp_` token straight to this
|
|
1278
|
+
machine's credential store (slot `agent:<name>`). The token is **never** returned in the
|
|
1279
|
+
tool result, printed, or logged — the result is `{name, crews, stored: true}`,
|
|
1280
|
+
built from scratch. It refuses a name that is already taken (the hub's error
|
|
1281
|
+
message is surfaced verbatim; error bodies never carry tokens). If the store
|
|
1282
|
+
write fails, the result says so and tells you to revoke/re-key the agent from
|
|
1283
|
+
the console.
|
|
1284
|
+
|
|
1285
|
+
**The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
|
|
1286
|
+
`remove_crew_member`) cover the same four operations as the [`crew` CLI
|
|
1287
|
+
family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
|
|
1288
|
+
rm` — over the same `/api/*` routes and the same RBAC, but they are not an
|
|
1289
|
+
exact mirror of it: `crew rm` (crew deletion) has no MCP counterpart at all
|
|
1290
|
+
(see below), and where the CLI narrows each hub response into one
|
|
1291
|
+
whitelisted JSON document per invocation (`asPools`, `asPoolCreated`, etc.,
|
|
1292
|
+
so `| jq` always works), these MCP tools are plain passthroughs — the raw
|
|
1293
|
+
hub REST body maps straight to the tool result with no narrowing. Each
|
|
1294
|
+
argument schema deliberately has **no `enum`** on `kind`/`principalKind`,
|
|
1295
|
+
since the hub, not this client, is the enforcement of record for which
|
|
1296
|
+
values are legal.
|
|
1297
|
+
|
|
1298
|
+
Access is **not uniformly admin-only**: `create_crew`, `add_crew_member`, and
|
|
1299
|
+
`remove_crew_member` all carry the same self-service carve-out as their CLI
|
|
1300
|
+
counterparts — a human acting on a **personal crew they own** needs no admin
|
|
1301
|
+
role at all (`assertPoolMutationAllowed`); every other target (a `shared`
|
|
1302
|
+
crew, or a `personal` crew owned by someone else) still requires the admin
|
|
1303
|
+
role. `list_crews` is readable by any of `admin`/`author`/`operator`.
|
|
1304
|
+
`remove_crew_member` is **tolerant**: removing a principal that was never a
|
|
1305
|
+
member is a normal `200` result with `removed: false`, never a tool error.
|
|
1306
|
+
`add_crew_member` is **not** tolerant the same way — adding a principal that
|
|
1307
|
+
is already a member is a hub error, mapped to an `isError` result. Both
|
|
1308
|
+
`add_crew_member` and `remove_crew_member` refuse the org's orphan crew
|
|
1309
|
+
(`orphan:unrouted`) as a `400`, never a `403` — the refusal is
|
|
1310
|
+
identity-independent (it objects to the target crew, not the caller's role),
|
|
1311
|
+
since that crew's membership is derived from the org's current admins and
|
|
1312
|
+
cannot be edited directly.
|
|
1313
|
+
|
|
1314
|
+
**`delete_crew` is deliberately NOT a tool here.** Deleting a crew is a
|
|
1315
|
+
one-way-door operation gated admin-only unconditionally on the hub (unlike
|
|
1316
|
+
the other three verbs, which have the self-service carve-out above), and it
|
|
1317
|
+
was excluded from this MCP surface by design. `owenloop crew rm` on the CLI
|
|
1318
|
+
remains the only way to delete a crew; removing a single **member** (above)
|
|
1319
|
+
is a different, reversible operation and stays in scope for MCP.
|
|
1320
|
+
|
|
1321
|
+
One further tool, `stage_enrollment`, is **conditionally** registered — it
|
|
1322
|
+
appears only when the hub advertises the staging endpoint (or when
|
|
1323
|
+
`OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
|
|
1324
|
+
redeems; a join code is transferred authority, not a credential, so it is safe
|
|
1325
|
+
to surface in a tool result. When the endpoint is absent, the tool is hidden
|
|
1326
|
+
(fail-closed).
|
|
1327
|
+
|
|
1328
|
+
### Authentication and secrets
|
|
1329
|
+
|
|
1330
|
+
Every tool call re-reads the stored `human` credential, refreshes it through the
|
|
1331
|
+
shared locked OAuth path if it is near expiry, and attaches it only as the
|
|
1332
|
+
`Authorization` header — the bearer never rides a tool result. Minted agent
|
|
1333
|
+
tokens (`create_agent`) are written to the local credential store and **never
|
|
1334
|
+
appear in any tool result, stderr line, or log**. If authentication fails
|
|
1335
|
+
(missing credential, refresh failure, or a final 401), the tool returns an error
|
|
1336
|
+
result whose text names the fix — run `owenloop login --hub <origin>` in a
|
|
1337
|
+
terminal — rather than prompting; the server itself never authenticates
|
|
1338
|
+
interactively.
|
|
1339
|
+
|
|
1340
|
+
### Environment knobs
|
|
1341
|
+
|
|
1342
|
+
| variable | effect |
|
|
1343
|
+
|---|---|
|
|
1344
|
+
| `OWENLOOP_HUB` | hub origin when `--hub` is absent (rung 2 of origin resolution) |
|
|
1345
|
+
| `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
|
|
1346
|
+
| `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
|
|
1347
|
+
| `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
|
|
1348
|
+
| `OWENLOOP_CRED_LOCK_WAIT_MS` / `OWENLOOP_CRED_LOCK_POLL_MS` | credential-lock wait/poll knobs (shared) |
|
|
1349
|
+
|
|
496
1350
|
## Hand-driven walkthrough
|
|
497
1351
|
|
|
498
1352
|
The [`examples/workflows`](../examples/workflows) folder has a workflow per
|
|
@@ -509,7 +1363,7 @@ codebase-advisor pipeline combining collections, a mid-flight human gate,
|
|
|
509
1363
|
per-element knock-backs, and suffixed-reduce fan-ins). Each example's header
|
|
510
1364
|
comment walks through its commands end to end.
|
|
511
1365
|
|
|
512
|
-
Playing every
|
|
1366
|
+
Playing every Step Agent yourself is the fastest way to internalize the loop.
|
|
513
1367
|
Every command prints JSON, so the snippet below pipes through `jq`:
|
|
514
1368
|
|
|
515
1369
|
```sh
|
|
@@ -527,7 +1381,7 @@ owenloop defs # what workflows are available
|
|
|
527
1381
|
wf=$(owenloop create delivery \
|
|
528
1382
|
--provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
|
|
529
1383
|
|
|
530
|
-
# the
|
|
1384
|
+
# the Step Agent loop: tick → run → report
|
|
531
1385
|
run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
|
|
532
1386
|
owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
|
|
533
1387
|
|
|
@@ -554,7 +1408,7 @@ instead of waiting for the next tick. `owenloop reap <wf>` runs that same
|
|
|
554
1408
|
cleanup on demand, applying the normal per-step/engine TTL rules — usually a
|
|
555
1409
|
no-op (`{ reaped: 0, details: [] }`). `owenloop reap <wf> --now` is the admin
|
|
556
1410
|
stand-down: it forces every currently-claimed task stale (TTL 0) regardless of
|
|
557
|
-
how fresh its claim is, for reclaiming a
|
|
1411
|
+
how fresh its claim is, for reclaiming a Step Agent you know is dead without
|
|
558
1412
|
waiting out the TTL. Reaping re-arms the task immediately, so **the run that
|
|
559
1413
|
held the cleared lease can no longer commit** — its next `green`/`close` fails
|
|
560
1414
|
with `run <id> no longer holds its lease (reaped or superseded)`, the same
|
|
@@ -594,13 +1448,13 @@ can be born-rejected too — a [judge's](authoring.md#judges--quality-gates-befo
|
|
|
594
1448
|
verdict lands on a stale `submitted` version (a sibling judge already settled
|
|
595
1449
|
it, the producer resubmitted, or a human bypassed it) and the CAS guard
|
|
596
1450
|
refuses it. The result JSON is always written to stdout; the human-readable
|
|
597
|
-
reason goes to stderr. A successful call exits 0 — a
|
|
1451
|
+
reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
|
|
598
1452
|
non-zero exit as a failure, not a success.
|
|
599
1453
|
|
|
600
1454
|
## What a job looks like
|
|
601
1455
|
|
|
602
1456
|
`tick` returns `{ workflow, orders, reaped }`. Each order is self-contained —
|
|
603
|
-
a
|
|
1457
|
+
a Step Agent needs nothing else to do the work:
|
|
604
1458
|
|
|
605
1459
|
```jsonc
|
|
606
1460
|
{
|
|
@@ -620,7 +1474,7 @@ a worker needs nothing else to do the work:
|
|
|
620
1474
|
}
|
|
621
1475
|
```
|
|
622
1476
|
|
|
623
|
-
A
|
|
1477
|
+
A Step Agent reads `prompt` + `consumes` + `owes`, does the work, reports with
|
|
624
1478
|
`green` (or `emit`/`seal` for collections), then `close`s the job. The reject
|
|
625
1479
|
counts in `owes[]` let a workflow escalate on its own — e.g. switch to a
|
|
626
1480
|
stronger model after two rejections — before the engine stalls the step.
|
|
@@ -636,25 +1490,25 @@ is the earliest wake across all levels. A folded deferral in the deep result
|
|
|
636
1490
|
carries its own `workflow` (absent = the root you ticked, present = a
|
|
637
1491
|
descendant).
|
|
638
1492
|
|
|
639
|
-
**
|
|
640
|
-
which steps this caller claims, but only steps that carry their own `
|
|
641
|
-
are ever excluded: a step is deferred with reason `
|
|
642
|
-
another caller **only** when its `
|
|
643
|
-
the filter you pass. A step with no `
|
|
644
|
-
filtered or not, and a tick that passes no `--
|
|
645
|
-
regardless of
|
|
1493
|
+
**Capability routing (`--capability`).** `tick <wf> --capability <l>` (repeatable) filters
|
|
1494
|
+
which steps this caller claims, but only steps that carry their own `capabilities:`
|
|
1495
|
+
are ever excluded: a step is deferred with reason `capability-mismatch` and left for
|
|
1496
|
+
another caller **only** when its `capabilities:` are non-empty and share no value with
|
|
1497
|
+
the filter you pass. A step with no `capabilities:` is claimed by every caller,
|
|
1498
|
+
filtered or not, and a tick that passes no `--capability` claims every eligible step
|
|
1499
|
+
regardless of capabilities. This is **routing, not
|
|
646
1500
|
authorization**: any caller that can reach the database can tick without a
|
|
647
|
-
filter and claim anything, so
|
|
1501
|
+
filter and claim anything, so capabilities split work across cooperating
|
|
648
1502
|
orchestrators, they never enforce a boundary. See
|
|
649
|
-
[`
|
|
1503
|
+
[`capabilities:`](authoring.md#capabilities--logical-capability-tags) in
|
|
650
1504
|
the authoring guide for the step-side declaration and the starvation hazard to
|
|
651
1505
|
watch for.
|
|
652
1506
|
|
|
653
1507
|
**Child stalls on `status`.** `status <wf>`'s `calls:`-debt entries carry a
|
|
654
1508
|
`child: { workflow, def, done, stalled, debts }` summary once a child has been
|
|
655
1509
|
spawned. `child.stalled: true` means the child (or a grandchild below it) has a
|
|
656
|
-
|
|
657
|
-
on stuck child work. This lets a
|
|
1510
|
+
Step Agent stuck at `maxAttempts` with no green outcome — the parent debt is blocked
|
|
1511
|
+
on stuck child work. This lets a Shift spot a wedged child from the parent
|
|
658
1512
|
`status` alone, without separately walking into the child's own `status`.
|
|
659
1513
|
|
|
660
1514
|
**`wait --until` is single-instance.** `wait <wf> --until eligible|done` polls
|