owenloop 0.4.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +58 -31
- 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/{cli.d.ts → src/cli.d.ts} +18 -3
- package/dist/{cli.js → src/cli.js} +770 -114
- package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
- package/dist/{credentials.js → src/credentials.js} +14 -12
- package/dist/{defs.js → src/defs.js} +36 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +14 -14
- package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
- package/dist/{hub.js → src/hub.js} +370 -12
- package/dist/{index.d.ts → src/index.d.ts} +1 -1
- package/dist/{index.js → src/index.js} +1 -1
- package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
- package/dist/{mcp → src/mcp}/serve.js +168 -31
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +6 -9
- package/dist/{model.js → src/model.js} +1 -1
- package/dist/{types.d.ts → src/types.d.ts} +18 -18
- package/dist/{util.d.ts → src/util.d.ts} +3 -2
- package/dist/{util.js → src/util.js} +3 -2
- package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
- package/dist/{owenwork.js → src/work-settings.js} +27 -27
- package/docs/authoring.md +93 -53
- package/docs/cli.md +597 -76
- package/docs/design.md +33 -33
- package/docs/embedding.md +10 -9
- 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/{add.d.ts → src/add.d.ts} +0 -0
- /package/dist/{add.js → src/add.js} +0 -0
- /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/{lock.d.ts → src/lock.d.ts} +0 -0
- /package/dist/{lock.js → src/lock.js} +0 -0
- /package/dist/{model.d.ts → src/model.d.ts} +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
|
@@ -49,13 +49,23 @@ for the full breakdown.
|
|
|
49
49
|
| `connect [--hub <url>] [--as <slot>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
|
|
50
50
|
| `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
|
|
51
51
|
| `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
|
|
52
|
-
| `agent new <name> [--
|
|
53
|
-
| `
|
|
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) |
|
|
54
62
|
| `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
|
|
55
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) |
|
|
56
66
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
57
67
|
| `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
|
|
58
|
-
| `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 |
|
|
59
69
|
| `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
|
|
60
70
|
| `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
|
|
61
71
|
| `status <wf>` | derived view: `done`, `debts`, `eligible`, `blocked`, `inFlight` |
|
|
@@ -73,6 +83,166 @@ for the full breakdown.
|
|
|
73
83
|
| `delete <wf>` | delete an instance and all its rows |
|
|
74
84
|
| `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
|
|
75
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
|
+
|
|
76
246
|
## `add` — installing shared workflow defs from GitHub
|
|
77
247
|
|
|
78
248
|
`owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
|
|
@@ -256,13 +426,13 @@ ref) surfaces as a 404 from the sha-resolve step.
|
|
|
256
426
|
**Trust model — what `add` does and does not protect.** Installing a package
|
|
257
427
|
executes nothing at install time: `add` only fetches, validates, and writes
|
|
258
428
|
YAML under the defs dir. But an installed def's steps *run* later, with
|
|
259
|
-
whatever privileges the host process and its dispatcher grant their
|
|
260
|
-
owenloop itself never executes a step body — `
|
|
261
|
-
|
|
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
|
|
262
432
|
not](../README.md#what-owenloop-is-not) and
|
|
263
|
-
[`docs/authoring.md`](authoring.md#
|
|
264
|
-
real risk surface is the
|
|
265
|
-
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
|
|
266
436
|
typically run with your full local privileges. **Install only sources you
|
|
267
437
|
trust.**
|
|
268
438
|
|
|
@@ -280,7 +450,7 @@ install *step* — staged all-or-nothing validation with an atomic swap, path
|
|
|
280
450
|
containment (including symlink-aware `bodyFile` checks), and archive resource
|
|
281
451
|
bounds — not the def *content* that later executes. `add` validates a def's
|
|
282
452
|
structure and contains its paths; it does not sandbox or sanitize what a step
|
|
283
|
-
body will do once a
|
|
453
|
+
body will do once a Step Agent runs it. That trust decision stays yours.
|
|
284
454
|
|
|
285
455
|
**Untrusted-archive safety.** `add` treats the fetched repo as untrusted and
|
|
286
456
|
refuses the whole install (nothing written) on any of these:
|
|
@@ -534,7 +704,7 @@ CLI.
|
|
|
534
704
|
|
|
535
705
|
### `agent new` — mint an agent token into a slot
|
|
536
706
|
|
|
537
|
-
`owenloop agent new <name>` mints a new
|
|
707
|
+
`owenloop agent new <name>` mints a new Scoped Identity on the hub (`POST
|
|
538
708
|
/api/mint_agent_token`, authenticated as your **human** credential) and stores
|
|
539
709
|
the returned `olp_` token in the local credential slot `agent:<name>` — the same
|
|
540
710
|
slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
|
|
@@ -544,9 +714,10 @@ happen in one step, and you never handle the secret.
|
|
|
544
714
|
**The token is never printed.** The minted `olp_` token goes process → store
|
|
545
715
|
only — it never appears on stdout, stderr, in an error, or in a log (identity
|
|
546
716
|
model §6, "rule of gates"). The confirmation JSON is built from a whitelist of
|
|
547
|
-
**non-secret** fields only: `hub`, `name`, `slot`, `
|
|
548
|
-
names), `scopes` (`["work"]`
|
|
549
|
-
|
|
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,
|
|
550
721
|
pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
|
|
551
722
|
on the hub.
|
|
552
723
|
|
|
@@ -567,47 +738,350 @@ production hub while you're logged into a dev one. Note that hub enumeration is
|
|
|
567
738
|
external-command backend cannot list their entries, so on such a machine step 2
|
|
568
739
|
cannot enumerate the store and you must pass `--hub`.
|
|
569
740
|
|
|
570
|
-
**`--
|
|
741
|
+
**`--crews <a,b>`.** A comma-separated list of crew names the token is granted
|
|
571
742
|
on (trimmed, empties dropped). Omit the flag to let the hub default the token to
|
|
572
|
-
the minter's personal
|
|
743
|
+
the minter's personal crew; `--crews ""` (or `--crews ,`) is a usage error. Crew
|
|
573
744
|
names are validated by the hub, not the client.
|
|
574
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
|
+
|
|
575
754
|
**A configured external credential command blocks the mint.** If
|
|
576
755
|
`OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
|
|
577
756
|
supplies credentials for the hub, so `agent new` refuses up front (it has
|
|
578
757
|
nowhere to write the minted token); unset the variable to use the local store.
|
|
579
|
-
This check, the name validation,
|
|
580
|
-
|
|
581
|
-
|
|
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.
|
|
582
762
|
|
|
583
763
|
**Exit codes.**
|
|
584
764
|
|
|
585
765
|
| code | meaning |
|
|
586
766
|
|---|---|
|
|
587
767
|
| `0` | minted and stored |
|
|
588
|
-
| `1` | generic failure — invalid or already-taken name,
|
|
768
|
+
| `1` | generic failure — invalid or already-taken name, crew/shape rejection, network timeout, or a token that minted but couldn't be stored |
|
|
589
769
|
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
590
770
|
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
591
771
|
|
|
592
|
-
##
|
|
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:
|
|
593
868
|
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
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:
|
|
599
1072
|
|
|
600
1073
|
1. **inspect** — read-only report of what's already present (human credential,
|
|
601
|
-
|
|
1074
|
+
execution settings, `claude` on PATH, agent slots). No writes.
|
|
602
1075
|
2. **human login** — verify the stored **human** credential, or run the same
|
|
603
1076
|
loopback-OAuth browser flow as `owenloop login` when none is present or it no
|
|
604
1077
|
longer verifies. This is the gate that makes step 3's mint/rekey legal.
|
|
605
1078
|
3. **agent** — find a local `agent:<name>` slot that verifies live against the
|
|
606
|
-
hub and reuse it; otherwise **mint** a new
|
|
1079
|
+
hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
|
|
607
1080
|
(replace the credential of) an existing one. How the target is chosen is
|
|
608
|
-
[below](#choosing-the-
|
|
609
|
-
4. **
|
|
610
|
-
the local
|
|
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).
|
|
611
1085
|
5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
|
|
612
1086
|
**Non-fatal:** while the marketplace is unpublished this step only *prints*
|
|
613
1087
|
the manual install commands (`claude plugin marketplace add owenloop` then
|
|
@@ -619,20 +1093,20 @@ Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
|
619
1093
|
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
620
1094
|
**stdout**.
|
|
621
1095
|
|
|
622
|
-
### Choosing the
|
|
1096
|
+
### Choosing the Scoped Identity (Flow A vs Flow B)
|
|
623
1097
|
|
|
624
|
-
When step 3 has to act (no reusable local agent slot), it decides *which*
|
|
1098
|
+
When step 3 has to act (no reusable local agent slot), it decides *which* Scoped Identity
|
|
625
1099
|
to connect this machine to:
|
|
626
1100
|
|
|
627
|
-
- **Flow A — fresh org (no
|
|
628
|
-
**name** the
|
|
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.
|
|
629
1103
|
The name is a suggestion — any label matching `[A-Za-z0-9][A-Za-z0-9._-]*`
|
|
630
|
-
(1–64 chars) is accepted. It then **mints** that
|
|
631
|
-
- **Flow B — org already has
|
|
632
|
-
|
|
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**)
|
|
633
1107
|
and asks whether this is a *new* installation or one that *replaces* an
|
|
634
|
-
existing
|
|
635
|
-
**rekeys** the chosen
|
|
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
|
|
636
1110
|
credential**, so if it is still running elsewhere it will be disconnected
|
|
637
1111
|
there.
|
|
638
1112
|
|
|
@@ -640,15 +1114,19 @@ to connect this machine to:
|
|
|
640
1114
|
scripted or piped run) and step 3 needs to act, setup will not block on a
|
|
641
1115
|
prompt — it errors unless you pre-decide with one of:
|
|
642
1116
|
|
|
643
|
-
- `--new-agent <name>` — mint a new
|
|
1117
|
+
- `--new-agent <name>` — mint a new Scoped Identity named `<name>` (skips Flow A's name
|
|
644
1118
|
prompt and Flow B's succession prompt).
|
|
645
|
-
- `--replace-agent <name>` — rekey the existing
|
|
646
|
-
succession prompt); errors if no such
|
|
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.
|
|
647
1121
|
|
|
648
|
-
The two flags are mutually exclusive. `--
|
|
1122
|
+
The two flags are mutually exclusive. `--crews <a,b>` applies **only** to a mint
|
|
649
1123
|
(`--new-agent` or a fresh org); combining it with `--replace-agent` is a usage
|
|
650
|
-
error, because rekeying preserves the
|
|
651
|
-
the console).
|
|
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`.
|
|
652
1130
|
|
|
653
1131
|
### Hub resolution differs from `agent new`
|
|
654
1132
|
|
|
@@ -678,8 +1156,8 @@ the flagship command never opens a browser only to fail at the store.)
|
|
|
678
1156
|
### After setup
|
|
679
1157
|
|
|
680
1158
|
If the connected agent account is anything other than `default`, setup prints a
|
|
681
|
-
reminder to run
|
|
682
|
-
right slot.
|
|
1159
|
+
reminder to run `owenloop work` with `OWENLOOP_ACCOUNT=<name>` so the Step Agent
|
|
1160
|
+
reads the right slot.
|
|
683
1161
|
|
|
684
1162
|
**Exit codes.**
|
|
685
1163
|
|
|
@@ -687,7 +1165,7 @@ right slot.
|
|
|
687
1165
|
|---|---|
|
|
688
1166
|
| `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
|
|
689
1167
|
| `1` | setup ran but doctor's core checks did not all pass |
|
|
690
|
-
| non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage
|
|
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 |
|
|
691
1169
|
|
|
692
1170
|
## `doctor` — check a machine's install
|
|
693
1171
|
|
|
@@ -708,7 +1186,7 @@ The checks, in order:
|
|
|
708
1186
|
| 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
|
|
709
1187
|
| 3 | agent slot | an `agent:<name>` credential is stored | yes |
|
|
710
1188
|
| 4 | agent plane | that agent credential verifies live against the hub | yes |
|
|
711
|
-
| 5 |
|
|
1189
|
+
| 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
|
|
712
1190
|
| 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
|
|
713
1191
|
|
|
714
1192
|
Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
|
|
@@ -764,7 +1242,9 @@ other command.
|
|
|
764
1242
|
### Tools
|
|
765
1243
|
|
|
766
1244
|
The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
|
|
767
|
-
`create_agent
|
|
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
|
|
768
1248
|
block; a non-2xx response comes back as an error result.
|
|
769
1249
|
|
|
770
1250
|
| tool | what it does |
|
|
@@ -783,20 +1263,61 @@ block; a non-2xx response comes back as an error result.
|
|
|
783
1263
|
| `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
|
|
784
1264
|
| `publish_event` | publish an event against a contract, starting one run per matched subscription |
|
|
785
1265
|
| `list_subscriptions` | the org's contract subscriptions |
|
|
786
|
-
| `presence_ping` | register/refresh this
|
|
787
|
-
| `
|
|
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 |
|
|
788
1268
|
| `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
|
|
789
|
-
| `create_agent` | create a NEW
|
|
790
|
-
|
|
791
|
-
`
|
|
792
|
-
`
|
|
793
|
-
|
|
794
|
-
|
|
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}`,
|
|
795
1280
|
built from scratch. It refuses a name that is already taken (the hub's error
|
|
796
1281
|
message is surfaced verbatim; error bodies never carry tokens). If the store
|
|
797
1282
|
write fails, the result says so and tells you to revoke/re-key the agent from
|
|
798
1283
|
the console.
|
|
799
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
|
+
|
|
800
1321
|
One further tool, `stage_enrollment`, is **conditionally** registered — it
|
|
801
1322
|
appears only when the hub advertises the staging endpoint (or when
|
|
802
1323
|
`OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
|
|
@@ -842,7 +1363,7 @@ codebase-advisor pipeline combining collections, a mid-flight human gate,
|
|
|
842
1363
|
per-element knock-backs, and suffixed-reduce fan-ins). Each example's header
|
|
843
1364
|
comment walks through its commands end to end.
|
|
844
1365
|
|
|
845
|
-
Playing every
|
|
1366
|
+
Playing every Step Agent yourself is the fastest way to internalize the loop.
|
|
846
1367
|
Every command prints JSON, so the snippet below pipes through `jq`:
|
|
847
1368
|
|
|
848
1369
|
```sh
|
|
@@ -860,7 +1381,7 @@ owenloop defs # what workflows are available
|
|
|
860
1381
|
wf=$(owenloop create delivery \
|
|
861
1382
|
--provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
|
|
862
1383
|
|
|
863
|
-
# the
|
|
1384
|
+
# the Step Agent loop: tick → run → report
|
|
864
1385
|
run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
|
|
865
1386
|
owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
|
|
866
1387
|
|
|
@@ -887,7 +1408,7 @@ instead of waiting for the next tick. `owenloop reap <wf>` runs that same
|
|
|
887
1408
|
cleanup on demand, applying the normal per-step/engine TTL rules — usually a
|
|
888
1409
|
no-op (`{ reaped: 0, details: [] }`). `owenloop reap <wf> --now` is the admin
|
|
889
1410
|
stand-down: it forces every currently-claimed task stale (TTL 0) regardless of
|
|
890
|
-
how fresh its claim is, for reclaiming a
|
|
1411
|
+
how fresh its claim is, for reclaiming a Step Agent you know is dead without
|
|
891
1412
|
waiting out the TTL. Reaping re-arms the task immediately, so **the run that
|
|
892
1413
|
held the cleared lease can no longer commit** — its next `green`/`close` fails
|
|
893
1414
|
with `run <id> no longer holds its lease (reaped or superseded)`, the same
|
|
@@ -927,13 +1448,13 @@ can be born-rejected too — a [judge's](authoring.md#judges--quality-gates-befo
|
|
|
927
1448
|
verdict lands on a stale `submitted` version (a sibling judge already settled
|
|
928
1449
|
it, the producer resubmitted, or a human bypassed it) and the CAS guard
|
|
929
1450
|
refuses it. The result JSON is always written to stdout; the human-readable
|
|
930
|
-
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
|
|
931
1452
|
non-zero exit as a failure, not a success.
|
|
932
1453
|
|
|
933
1454
|
## What a job looks like
|
|
934
1455
|
|
|
935
1456
|
`tick` returns `{ workflow, orders, reaped }`. Each order is self-contained —
|
|
936
|
-
a
|
|
1457
|
+
a Step Agent needs nothing else to do the work:
|
|
937
1458
|
|
|
938
1459
|
```jsonc
|
|
939
1460
|
{
|
|
@@ -953,7 +1474,7 @@ a worker needs nothing else to do the work:
|
|
|
953
1474
|
}
|
|
954
1475
|
```
|
|
955
1476
|
|
|
956
|
-
A
|
|
1477
|
+
A Step Agent reads `prompt` + `consumes` + `owes`, does the work, reports with
|
|
957
1478
|
`green` (or `emit`/`seal` for collections), then `close`s the job. The reject
|
|
958
1479
|
counts in `owes[]` let a workflow escalate on its own — e.g. switch to a
|
|
959
1480
|
stronger model after two rejections — before the engine stalls the step.
|
|
@@ -969,25 +1490,25 @@ is the earliest wake across all levels. A folded deferral in the deep result
|
|
|
969
1490
|
carries its own `workflow` (absent = the root you ticked, present = a
|
|
970
1491
|
descendant).
|
|
971
1492
|
|
|
972
|
-
**
|
|
973
|
-
which steps this caller claims, but only steps that carry their own `
|
|
974
|
-
are ever excluded: a step is deferred with reason `
|
|
975
|
-
another caller **only** when its `
|
|
976
|
-
the filter you pass. A step with no `
|
|
977
|
-
filtered or not, and a tick that passes no `--
|
|
978
|
-
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
|
|
979
1500
|
authorization**: any caller that can reach the database can tick without a
|
|
980
|
-
filter and claim anything, so
|
|
1501
|
+
filter and claim anything, so capabilities split work across cooperating
|
|
981
1502
|
orchestrators, they never enforce a boundary. See
|
|
982
|
-
[`
|
|
1503
|
+
[`capabilities:`](authoring.md#capabilities--logical-capability-tags) in
|
|
983
1504
|
the authoring guide for the step-side declaration and the starvation hazard to
|
|
984
1505
|
watch for.
|
|
985
1506
|
|
|
986
1507
|
**Child stalls on `status`.** `status <wf>`'s `calls:`-debt entries carry a
|
|
987
1508
|
`child: { workflow, def, done, stalled, debts }` summary once a child has been
|
|
988
1509
|
spawned. `child.stalled: true` means the child (or a grandchild below it) has a
|
|
989
|
-
|
|
990
|
-
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
|
|
991
1512
|
`status` alone, without separately walking into the child's own `status`.
|
|
992
1513
|
|
|
993
1514
|
**`wait --until` is single-instance.** `wait <wf> --until eligible|done` polls
|