owenloop 0.5.7 → 0.5.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +41 -0
- package/README.md +7 -8
- package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
- package/dist/packages/work/src/agent/capability-model.js +94 -91
- package/dist/packages/work/src/agent/loop.d.ts +55 -26
- package/dist/packages/work/src/agent/loop.js +144 -50
- package/dist/packages/work/src/bundle/types.d.ts +3 -3
- package/dist/packages/work/src/consumed-verifier.js +6 -17
- package/dist/packages/work/src/exec/loop.d.ts +1 -1
- package/dist/packages/work/src/exec/loop.js +206 -35
- package/dist/packages/work/src/exec/receipt.d.ts +7 -7
- package/dist/packages/work/src/exec/receipt.js +6 -6
- package/dist/packages/work/src/harness/child-env.js +4 -5
- package/dist/packages/work/src/harness/claude.js +100 -0
- package/dist/packages/work/src/harness/codex.js +3 -4
- package/dist/packages/work/src/harness/session-store.d.ts +63 -3
- package/dist/packages/work/src/harness/session-store.js +104 -9
- package/dist/packages/work/src/hub/client.d.ts +19 -4
- package/dist/packages/work/src/hub/client.js +7 -3
- package/dist/packages/work/src/hub/types.d.ts +87 -3
- package/dist/packages/work/src/main.js +1 -0
- package/dist/packages/work/src/roles/agent-run.js +46 -43
- package/dist/packages/work/src/roles/exec.js +2 -0
- package/dist/packages/work/src/roles/sessions.d.ts +3 -2
- package/dist/packages/work/src/roles/sessions.js +9 -2
- package/dist/packages/work/src/roles/settings.js +3 -1
- package/dist/packages/work/src/roles/shift.js +14 -2
- package/dist/packages/work/src/roles/util.d.ts +1 -0
- package/dist/packages/work/src/roles/util.js +10 -0
- package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
- package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
- package/dist/packages/work/src/settings/roster.d.ts +105 -0
- package/dist/packages/work/src/settings/roster.js +439 -0
- package/dist/packages/work/src/settings/serving.d.ts +17 -0
- package/dist/packages/work/src/settings/serving.js +79 -0
- package/dist/packages/work/src/settings/settings.d.ts +25 -24
- package/dist/packages/work/src/settings/settings.js +29 -33
- package/dist/packages/work/src/shift/loop.d.ts +108 -5
- package/dist/packages/work/src/shift/loop.js +299 -51
- package/dist/packages/work/src/shift/protocol.d.ts +7 -5
- package/dist/packages/work/src/shift/runtime.d.ts +15 -0
- package/dist/packages/work/src/shift/runtime.js +95 -13
- package/dist/packages/work/src/shift/server.js +2 -0
- package/dist/packages/work/src/shift/spawn.d.ts +18 -50
- package/dist/packages/work/src/shift/spawn.js +30 -65
- package/dist/packages/work/src/shift/state.d.ts +29 -2
- package/dist/packages/work/src/shift/state.js +45 -15
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +10 -5
- package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
- package/dist/packages/work/src/util/modifier-init.js +73 -0
- package/dist/src/bundle/tar.d.ts +9 -4
- package/dist/src/bundle/tar.js +9 -4
- package/dist/src/capabilities.d.ts +50 -0
- package/dist/src/capabilities.js +38 -0
- package/dist/src/cli.d.ts +15 -1
- package/dist/src/cli.js +1099 -32
- package/dist/src/config-dir.d.ts +14 -19
- package/dist/src/config-dir.js +16 -24
- package/dist/src/credentials.d.ts +1 -1
- package/dist/src/credentials.js +1 -1
- package/dist/src/crypto/index.d.ts +1 -1
- package/dist/src/crypto/index.js +1 -1
- package/dist/src/crypto/org-root.d.ts +30 -12
- package/dist/src/crypto/org-root.js +162 -14
- package/dist/src/crypto/records.d.ts +3 -0
- package/dist/src/crypto/records.js +8 -0
- package/dist/src/crypto/trust-roots.d.ts +2 -2
- package/dist/src/crypto/trust-roots.js +2 -2
- package/dist/src/defs.d.ts +6 -1
- package/dist/src/defs.js +203 -8
- package/dist/src/engine.d.ts +55 -6
- package/dist/src/engine.js +172 -22
- package/dist/src/global-config.d.ts +4 -7
- package/dist/src/global-config.js +4 -7
- package/dist/src/hub.d.ts +207 -5
- package/dist/src/hub.js +263 -3
- package/dist/src/index.d.ts +5 -5
- package/dist/src/index.js +3 -3
- package/dist/src/mcp/serve.d.ts +22 -0
- package/dist/src/mcp/serve.js +88 -8
- package/dist/src/model.d.ts +2 -0
- package/dist/src/model.js +32 -25
- package/dist/src/order-resolver.d.ts +1 -0
- package/dist/src/order-resolver.js +8 -1
- package/dist/src/schemas/index.d.ts +19 -0
- package/dist/src/schemas/order.v1.schema.json +13 -2
- package/dist/src/store/pre-commit-verifier.js +1 -1
- package/dist/src/store.d.ts +5 -0
- package/dist/src/store.js +43 -8
- package/dist/src/types.d.ts +64 -7
- package/dist/src/work-settings.d.ts +2 -4
- package/dist/src/work-settings.js +2 -4
- package/docs/agent-runner.md +2 -2
- package/docs/authoring.md +90 -2
- package/docs/bundles.md +29 -3
- package/docs/cli.md +456 -120
- package/docs/crypto.md +32 -16
- package/docs/design.md +70 -1
- package/docs/routing.md +762 -0
- package/docs/shift-logs.md +37 -10
- package/docs/wire-contracts.md +50 -7
- package/examples/workflows/delivery.yaml +31 -14
- package/examples/workflows/ship.yaml +10 -2
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
package/docs/routing.md
ADDED
|
@@ -0,0 +1,762 @@
|
|
|
1
|
+
# Routing: how a step in a workflow reaches a model
|
|
2
|
+
|
|
3
|
+
This document explains the whole path from "a workflow definition says this
|
|
4
|
+
step needs a builder" to "a specific model, at a specific reasoning effort, on
|
|
5
|
+
a specific CLI, does the work."
|
|
6
|
+
|
|
7
|
+
It is written to be read once, start to finish, by someone who has never seen
|
|
8
|
+
the system. Every term is defined before it is used. Nothing is left implicit.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 0. Status of this document
|
|
13
|
+
|
|
14
|
+
Sections 1 through 8 describe behavior that is live today, with one
|
|
15
|
+
explicitly marked exception inside section 8a.
|
|
16
|
+
|
|
17
|
+
Section 9 (**When nobody is certified**) describes a rule that is CHANGING.
|
|
18
|
+
Both the old rule and the new rule are stated, and it is marked which is which,
|
|
19
|
+
because a deployment running an older hub still does the old thing.
|
|
20
|
+
|
|
21
|
+
Section 10 (**Reroute rules**) describes a feature whose engine, hub and CLI
|
|
22
|
+
halves are now in place; the MCP surface is not. It is marked as such.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 1. The four words
|
|
27
|
+
|
|
28
|
+
The single biggest source of confusion is the word **capability**. It sounds
|
|
29
|
+
like a property of a machine — "this box can run Opus." It is not that at all.
|
|
30
|
+
|
|
31
|
+
Use this mapping instead. It is exact, not a loose analogy.
|
|
32
|
+
|
|
33
|
+
| Term | Think of it as | Who writes it | Where it lives |
|
|
34
|
+
|---|---|---|---|
|
|
35
|
+
| **capability** | a **job posting** | the workflow author | the workflow definition file (`delivery.yaml`) |
|
|
36
|
+
| **modifier** | the **grade on the posting** | the starter at `start_run`, then the engine through a declared artifact bind | the run instance; an optional bound artifact is the writer |
|
|
37
|
+
| **crew** | a **team certified for that posting** | the hub operator | the hub's `capability_routes` table |
|
|
38
|
+
| **shift** | a **team member clocking in** | whoever runs the machine | a local `settings.json` on that machine |
|
|
39
|
+
|
|
40
|
+
Read as one sentence:
|
|
41
|
+
|
|
42
|
+
> A **workflow definition** posts a job (`build`). The person starting the run
|
|
43
|
+
> stamps a grade on it (`deep`), making the posting `build:deep`. The **hub**
|
|
44
|
+
> looks up which **crews** are certified for `build:deep`. A **shift** — one
|
|
45
|
+
> member of a certified crew, currently clocked in — takes the job and decides,
|
|
46
|
+
> from its own local settings, which model and effort to run it on.
|
|
47
|
+
|
|
48
|
+
Four things follow from that sentence, and all four are places people get it
|
|
49
|
+
wrong:
|
|
50
|
+
|
|
51
|
+
1. **A capability never names a model.** `build` does not mean "Opus." It means
|
|
52
|
+
"somebody who does building." The model is chosen at the very last step, by
|
|
53
|
+
the shift, from its own settings file.
|
|
54
|
+
2. **A capability never names a machine.** Nothing in the definition or the hub
|
|
55
|
+
knows what hardware or CLI exists.
|
|
56
|
+
3. **Certifying a crew is a promise about every member.** Binding `build:deep`
|
|
57
|
+
to the crew `openai` says: *every shift that serves the openai crew can do
|
|
58
|
+
deep build work.* If one member cannot, the binding is wrong.
|
|
59
|
+
4. **The mapping is many-to-many, both directions.** One capability can be
|
|
60
|
+
bound to several crews. One crew can be bound to several capabilities. One
|
|
61
|
+
shift can serve several crews (`owenloop shift start anthropic openai`
|
|
62
|
+
takes a list). On the staging hub every shift serves exactly one crew, so
|
|
63
|
+
this shows the shape of the argument rather than a shift that exists today.
|
|
64
|
+
|
|
65
|
+
The final model choice is a separate **roster** cascade. A shift refreshes the
|
|
66
|
+
hub organization rosters into its local disk cache, then the spawned
|
|
67
|
+
`agent-run` child reads that cache offline. For a named crew the strongest-first
|
|
68
|
+
layers are machine `crews/<crew>.json`, machine `settings.json`, cached hub
|
|
69
|
+
crew roster, and cached hub org-global roster. The cached hub layers are
|
|
70
|
+
deliberately weakest; an unavailable cache is visible in `owenloop roster show`
|
|
71
|
+
but never makes a shift or order fail when a machine row can route it.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 2. The three vocabularies, precisely
|
|
76
|
+
|
|
77
|
+
There are exactly three kinds of capability string, and they are different
|
|
78
|
+
things. Mixing them up is the second biggest source of confusion.
|
|
79
|
+
|
|
80
|
+
**Authored capability** — what a workflow step declares. Never contains a
|
|
81
|
+
colon.
|
|
82
|
+
|
|
83
|
+
```yaml
|
|
84
|
+
- name: builder
|
|
85
|
+
capabilities: [build] # <- authored capability
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Modifier** — one word, carried by the run instance. The starter supplies the
|
|
89
|
+
initial value; after that, a def-declared artifact bind is the only thing that
|
|
90
|
+
can change it (section 8a). The engine attaches *no meaning*
|
|
91
|
+
to it. `deep` is not "more" than `express` as far as any code is concerned;
|
|
92
|
+
they are just two different strings. A definition declares which ones it
|
|
93
|
+
accepts. One word is a rule, not a convention: `modifiers:` refuses a name
|
|
94
|
+
containing whitespace at definition-parse time (`parseModifiers` in
|
|
95
|
+
`src/defs.ts`), so a spaced name fails at publish rather than at bind:
|
|
96
|
+
|
|
97
|
+
```yaml
|
|
98
|
+
modifiers: [express, standard, deep]
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**Compound capability** — an authored capability with a modifier glued on by a
|
|
102
|
+
colon: `build:deep`. **Nobody writes this by hand in a workflow definition.**
|
|
103
|
+
It is composed by the engine at the moment an order is offered, by
|
|
104
|
+
`composeCapabilities(step.capabilities, modifier)` in `src/capabilities.ts`.
|
|
105
|
+
|
|
106
|
+
A run with no modifier composes to the bare authored capability. `build` stays
|
|
107
|
+
`build`. There is no default modifier — omitting `--modifier` does not mean
|
|
108
|
+
`standard`, it means *no modifier at all*.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 3. Where each fact physically lives
|
|
113
|
+
|
|
114
|
+
Three files, three different owners, three different machines potentially.
|
|
115
|
+
|
|
116
|
+
### 3a. The workflow definition — "what job is this?"
|
|
117
|
+
|
|
118
|
+
A `.yaml` in a bundle, e.g. `owenloop-delivery/workflows/delivery.yaml`.
|
|
119
|
+
|
|
120
|
+
```yaml
|
|
121
|
+
modifiers: [express, standard, deep]
|
|
122
|
+
|
|
123
|
+
steps:
|
|
124
|
+
- name: planner
|
|
125
|
+
capabilities: [wise]
|
|
126
|
+
- name: builder
|
|
127
|
+
capabilities: [build]
|
|
128
|
+
- name: reviewer
|
|
129
|
+
capabilities: [review]
|
|
130
|
+
- name: provisioner
|
|
131
|
+
capabilities: [utility]
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
This file names jobs. It names no models, no crews, no machines.
|
|
135
|
+
|
|
136
|
+
### 3b. The hub's `capability_routes` table — "who is certified?"
|
|
137
|
+
|
|
138
|
+
A table inside the hub, one row per `(capability string, crew)` pair. Written
|
|
139
|
+
with `owenloop capability bind <capability> <crew>`.
|
|
140
|
+
|
|
141
|
+
The staging hub's current rows are exactly these sixteen:
|
|
142
|
+
|
|
143
|
+
| capability | crew |
|
|
144
|
+
|---|---|
|
|
145
|
+
| `wise` | `anthropic` |
|
|
146
|
+
| `wise:express` | `anthropic` |
|
|
147
|
+
| `wise:standard` | `anthropic` |
|
|
148
|
+
| `wise:deep` | `anthropic` |
|
|
149
|
+
| `build` | `openai` |
|
|
150
|
+
| `build:express` | `openai` |
|
|
151
|
+
| `build:standard` | `openai` |
|
|
152
|
+
| `build:deep` | `openai` |
|
|
153
|
+
| `review` | `openai` |
|
|
154
|
+
| `review:express` | `openai` |
|
|
155
|
+
| `review:standard` | `openai` |
|
|
156
|
+
| `review:deep` | `openai` |
|
|
157
|
+
| `utility` | `openai` |
|
|
158
|
+
| `utility:express` | `openai` |
|
|
159
|
+
| `utility:standard` | `openai` |
|
|
160
|
+
| `utility:deep` | `openai` |
|
|
161
|
+
|
|
162
|
+
The live table gives the `anthropic` crew one job family and its modifiers:
|
|
163
|
+
the four `wise` strings. It gives the `openai` crew three job families and
|
|
164
|
+
their modifiers: `build`, `review`, and `utility`. A crew name says which
|
|
165
|
+
team; a capability says which job. Nothing in `anthropic` or `openai` tells
|
|
166
|
+
you what job it does, and that is correct — the crew name is not supposed to.
|
|
167
|
+
|
|
168
|
+
A capability can still be certified to a crew whose name has nothing to do with
|
|
169
|
+
the job. If an operator wanted deep build work on Anthropic models, the
|
|
170
|
+
operator would run:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
owenloop capability bind build:deep anthropic
|
|
174
|
+
owenloop capability unbind build:deep openai
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
The *job* is still a build job. Only the *team* changes.
|
|
178
|
+
|
|
179
|
+
These are two commands, not one. `capability bind` on an already-bound
|
|
180
|
+
capability **adds** a crew; it never replaces one. With only the bind,
|
|
181
|
+
`build:deep` would be certified to both `openai` and `anthropic`, and
|
|
182
|
+
which crew's shift claims a given order would be a race. The unbind is what
|
|
183
|
+
makes it a move. This is verified by `src/cli.ts:5079` and independently by
|
|
184
|
+
`docs/authoring.md:254`.
|
|
185
|
+
|
|
186
|
+
That hypothetical move also needs a rate-card change. The shift first looks
|
|
187
|
+
for an exact `build:deep` row and then may fall back to a bare `build` row.
|
|
188
|
+
The `anthropic` card shown here has neither row, so after the rebind it would
|
|
189
|
+
refuse the order with `unresolvable-capability`, and the hub would re-offer it.
|
|
190
|
+
If the card had a bare `build` row, the shift would run that row's potentially
|
|
191
|
+
different model and effort instead. The operator must add an intentional
|
|
192
|
+
`build:deep` row to the `anthropic` card as part of the same move.
|
|
193
|
+
|
|
194
|
+
### 3c. The crew roster — “what can this machine run?”
|
|
195
|
+
A machine's global fallback lives under the `roster` key in
|
|
196
|
+
`~/.owenloop/settings.json`; a named crew's stronger layer is
|
|
197
|
+
`~/.owenloop/crews/<crew>.json`. Both files use the same top-level shape:
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"roster": {
|
|
202
|
+
"wise:deep": [
|
|
203
|
+
{ "harness": "claude-code", "model": "claude-fable-5", "effort": "xhigh" },
|
|
204
|
+
{ "harness": "codex", "model": "gpt-5.6-sol", "effort": "xhigh" }
|
|
205
|
+
],
|
|
206
|
+
"wise": [
|
|
207
|
+
{ "harness": "claude-code", "model": "claude-opus-5", "effort": "high" }
|
|
208
|
+
]
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Every value is a non-empty ordered candidate array. The stronger crew layer
|
|
214
|
+
replaces a capability's full array from the machine-global layer; arrays are
|
|
215
|
+
never combined. Exact composed capability lookup runs before bare-name lookup
|
|
216
|
+
across all offered capabilities. The first candidate whose harness is
|
|
217
|
+
registered wins, unless a step's `x.harness.id` requires a different harness.
|
|
218
|
+
That mismatch is an `incompatible-harness-policy` release; no registered
|
|
219
|
+
candidate is `unresolvable-capability`.
|
|
220
|
+
|
|
221
|
+
### 4. The four things a shift is configured with
|
|
222
|
+
|
|
223
|
+
A shift start command names its crews, credentials, display identity, and
|
|
224
|
+
state directory. It no longer carries an operator-selected harness or a
|
|
225
|
+
per-shift config directory. Its crews are the worker → hub
|
|
226
|
+
`serve_crews` narrowing advertisement. It also sends a derived
|
|
227
|
+
`serve_capabilities` advertisement: the sorted raw keys from its effective
|
|
228
|
+
merged rosters, with bare names and exact compounds mixed. `[]` means
|
|
229
|
+
"clocked in, serving nothing." This can only narrow offers; it never grants
|
|
230
|
+
authority, and the shift passes NO crews to agent children. **Today's hub
|
|
231
|
+
ignores `serve_capabilities`; the hub-side intersect ships separately.** For a
|
|
232
|
+
capability-bearing order, the hub stamps its matched crews on the order and the
|
|
233
|
+
agent resolves those rosters in the stamped order.
|
|
234
|
+
|
|
235
|
+
| Name | What it selects |
|
|
236
|
+
|---|---|
|
|
237
|
+
| **crew** (positional) | worker → hub `serve_crews` offer scope; the hub-stamped `order.crews` resolves the agent worker's roster sequence |
|
|
238
|
+
| **`--as`** | which stored credential to authenticate with |
|
|
239
|
+
| **`--name`** | a display label for this shift |
|
|
240
|
+
| **`--state-dir`** | local socket and child-state storage |
|
|
241
|
+
|
|
242
|
+
Use `owenloop roster show [crew]` to see each selected candidate and the
|
|
243
|
+
layer that supplied it. `owenloop doctor` reports the same layers and whether
|
|
244
|
+
their candidate harnesses are registered.
|
|
245
|
+
|
|
246
|
+
## 5. What actually happens when an order is offered
|
|
247
|
+
|
|
248
|
+
Here is one order, end to end, in order.
|
|
249
|
+
|
|
250
|
+
**Step 1 — a human starts a run.**
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
owenloop start delivery --modifier deep \
|
|
254
|
+
--provide proposal='{"text":"..."}' \
|
|
255
|
+
--provide target='{"path":"/Users/alex/code/owenloop"}'
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
The hub creates an instance and stores `modifier = "deep"` on it as the run's
|
|
259
|
+
initial hint. A def may later declare one artifact with `bind: modifier`; when
|
|
260
|
+
that artifact is accepted, the engine synchronizes the instance's modifier in
|
|
261
|
+
the same acceptance transaction. There is still no general-purpose verb that
|
|
262
|
+
lets a worker write the column.
|
|
263
|
+
|
|
264
|
+
**Step 2 — a shift asks for work.**
|
|
265
|
+
|
|
266
|
+
The `openai-1` shift calls the hub verb `whats_next`, authenticating as
|
|
267
|
+
account `shift-openai-1`. Alongside its `serve_crews` scope it sends
|
|
268
|
+
`serve_capabilities`: raw keys from the merged roster cascade. A bare key is
|
|
269
|
+
not expanded locally, because the shift does not know the modifier vocabulary.
|
|
270
|
+
|
|
271
|
+
**Step 3 — the hub works out what this caller is authorized to do today.**
|
|
272
|
+
|
|
273
|
+
Today's hub still ignores the shift's `serve_capabilities` field. The
|
|
274
|
+
hub-side intersect-before-match is a separately shipped follow-up. Instead,
|
|
275
|
+
the current hub:
|
|
276
|
+
|
|
277
|
+
- it looks up which crews the account `shift-openai-1` belongs to;
|
|
278
|
+
- it reads every `capability_routes` row for those crews;
|
|
279
|
+
- the resulting list of capability strings is the caller's capability set.
|
|
280
|
+
|
|
281
|
+
The function is `listCapabilitiesForCrews(storage, memberCrewIds)`. For the
|
|
282
|
+
`openai-1` shift on staging that yields this set:
|
|
283
|
+
|
|
284
|
+
```
|
|
285
|
+
['build', 'build:deep', 'build:express', 'build:standard',
|
|
286
|
+
'review', 'review:deep', 'review:express', 'review:standard',
|
|
287
|
+
'utility', 'utility:deep', 'utility:express', 'utility:standard']
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
The strings are shown alphabetically for readability; their order is not
|
|
291
|
+
significant.
|
|
292
|
+
|
|
293
|
+
This is why point 3 in section 1 matters: **authority comes entirely from crew
|
|
294
|
+
membership.** A shift can advertise a local offer filter, but cannot claim,
|
|
295
|
+
declare, or negotiate authority for a capability.
|
|
296
|
+
|
|
297
|
+
**Step 4 — the engine composes the posting.**
|
|
298
|
+
|
|
299
|
+
For the `builder` step, whose authored capability is `build`, and a run whose
|
|
300
|
+
modifier is `deep`:
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
composeCapabilities(['build'], 'deep') -> ['build:deep']
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
The order will be offered as `build:deep`.
|
|
307
|
+
|
|
308
|
+
**Step 5 — the hub decides how strictly to match.**
|
|
309
|
+
|
|
310
|
+
For each composed capability, the hub asks: *is any live crew certified for
|
|
311
|
+
this exact string?* "Live" means the `capability_routes` row exists **and** the
|
|
312
|
+
crew it names still exists — a row pointing at a deleted crew is dangling and
|
|
313
|
+
counts as nothing.
|
|
314
|
+
|
|
315
|
+
- `build:deep` has a live row (crew `openai`) → match mode **`exact`**. Only
|
|
316
|
+
crews certified for the exact string `build:deep` may claim.
|
|
317
|
+
- If it had no live row → see section 9.
|
|
318
|
+
|
|
319
|
+
**Step 6 — the match.**
|
|
320
|
+
|
|
321
|
+
`claimMatches(offered, caller, modes)`. Offered is `['build:deep']`. The
|
|
322
|
+
`openai-1` shift's caller set contains `build:deep`. Under `exact` mode
|
|
323
|
+
that is a match. The order is handed to `openai-1`, with
|
|
324
|
+
`order.capabilities = ['build:deep']`.
|
|
325
|
+
|
|
326
|
+
The `anthropic` shift, whose caller set is
|
|
327
|
+
`['wise', 'wise:deep', 'wise:express', 'wise:standard']`, does **not** match
|
|
328
|
+
— it is not certified for `build:deep`. That is the correct outcome, and it
|
|
329
|
+
is what stops a deep build job landing on the Anthropic shift. The two caller
|
|
330
|
+
sets do not overlap at all, which is exactly what it looks like when
|
|
331
|
+
eligibility comes entirely from crew membership and the crews are named after
|
|
332
|
+
teams.
|
|
333
|
+
|
|
334
|
+
**Step 7 — the worker picks the model.**
|
|
335
|
+
|
|
336
|
+
The agent reads `order.capabilities` — `['build:deep']` — plus the hub →
|
|
337
|
+
worker `order.crews` stamp, and resolves those merged crew rosters in order:
|
|
338
|
+
|
|
339
|
+
1. Try the **exact compound**: `build:deep` → an ordered candidate array. Found.
|
|
340
|
+
2. If not found, try the **bare name part**: `build`.
|
|
341
|
+
3. If neither is found, the worker **refuses the order** with
|
|
342
|
+
`unresolvable-capability` and the hub re-offers it.
|
|
343
|
+
|
|
344
|
+
An absent, empty, malformed, or unreadable crew stamp is also refused and
|
|
345
|
+
released; there is no fallback to the crews the shift was started with. These
|
|
346
|
+
are real, deliberate refusals, not crashes. A worker that has no rate for a job
|
|
347
|
+
does not guess a model.
|
|
348
|
+
|
|
349
|
+
**Step 8 — the harness runs it.**
|
|
350
|
+
|
|
351
|
+
the selected roster candidate for the openai shifts, so the Codex CLI is spawned
|
|
352
|
+
with model `gpt-5.6-terra` and effort `xhigh`.
|
|
353
|
+
|
|
354
|
+
Valid efforts, in order: `low`, `medium`, `high`, `xhigh`, `max`.
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## 6. Why the model is chosen last, not first
|
|
359
|
+
|
|
360
|
+
A reasonable person asks: why not just write the model in the workflow
|
|
361
|
+
definition?
|
|
362
|
+
|
|
363
|
+
Because the definition is shared and the hardware is not. The same
|
|
364
|
+
`delivery.yaml` runs on a laptop with one API key, a CI box with another, and
|
|
365
|
+
someone else's fork entirely. A model name in the definition would be a promise
|
|
366
|
+
the author cannot keep.
|
|
367
|
+
|
|
368
|
+
So the definition says what *kind* of worker it needs. The hub says which
|
|
369
|
+
*teams* are certified. The machine owner says what those teams *run on*. Each
|
|
370
|
+
layer states only what it actually knows.
|
|
371
|
+
|
|
372
|
+
---
|
|
373
|
+
|
|
374
|
+
## 7. Two shifts, one crew — and when that is wrong
|
|
375
|
+
|
|
376
|
+
The `openai` crew has exactly two staging shifts: `openai-1` and `openai-2`.
|
|
377
|
+
Both run codex and carry the same rate card. Because a crew is a team, both
|
|
378
|
+
become eligible for that crew's jobs.
|
|
379
|
+
|
|
380
|
+
**This works, with one consequence you must accept: which member gets the order
|
|
381
|
+
is a race.** First claim wins. The hub does not choose between eligible
|
|
382
|
+
members.
|
|
383
|
+
|
|
384
|
+
That is fine for a job where you genuinely do not care which member claims it
|
|
385
|
+
— a generic `coder` posting where either shift is acceptable.
|
|
386
|
+
|
|
387
|
+
For this staging pair, the two `openai` shifts must carry byte-identical rate
|
|
388
|
+
cards. Crew membership is what makes a shift eligible, and both members are
|
|
389
|
+
eligible for every capability the crew is certified for. If `openai-2` were
|
|
390
|
+
missing a row that `openai-1` has, the hub would eventually hand `openai-2` an
|
|
391
|
+
order it cannot price; `openai-2` would refuse with
|
|
392
|
+
`unresolvable-capability`; the hub would re-offer the order. That is the
|
|
393
|
+
claim-refuse-reoffer loop, and nothing about it is visible from the hub side —
|
|
394
|
+
the routing table is identical in both cases. This is why section 3c says both
|
|
395
|
+
openai cards are byte-identical.
|
|
396
|
+
|
|
397
|
+
This is a property of these two shifts sharing the `codex` adapter, not a
|
|
398
|
+
universal rule for every pair of shifts serving one crew. Shifts on different
|
|
399
|
+
adapters may use different model ids and separate settings directories; the
|
|
400
|
+
invariant is that every eligible shift must be able to resolve every capability
|
|
401
|
+
the crew is certified for.
|
|
402
|
+
|
|
403
|
+
It is exactly wrong for `wise:deep`, where the entire point is "this specific
|
|
404
|
+
one must be claude-fable-5." `wise:deep` is certified to `anthropic`, and
|
|
405
|
+
the anthropic card serves it with `claude-fable-5`, a different model from
|
|
406
|
+
every other `wise` row. If you want a guarantee about *which model*, you need
|
|
407
|
+
a crew whose members all run that model, and you certify that crew for the
|
|
408
|
+
compound.
|
|
409
|
+
|
|
410
|
+
One more failure mode: a step can declare a permission policy an adapter cannot
|
|
411
|
+
enforce (see `x.harness` in a step definition). A member on the wrong harness
|
|
412
|
+
releases the order with `incompatible-harness-policy`, and the hub re-offers it.
|
|
413
|
+
So a mixed crew can also produce a claim-then-release loop if the step's policy
|
|
414
|
+
is adapter-specific.
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## 8. Escalation — the per-step, temporary grade change
|
|
419
|
+
|
|
420
|
+
A step can declare an escalation:
|
|
421
|
+
|
|
422
|
+
```yaml
|
|
423
|
+
- name: builder
|
|
424
|
+
capabilities: [build]
|
|
425
|
+
escalation:
|
|
426
|
+
after: 3
|
|
427
|
+
modifier: deep
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Read: *after this step's owed artifact has been judgment-rejected 3 times,
|
|
431
|
+
re-offer this step composed with `deep` instead of the run's own modifier.*
|
|
432
|
+
|
|
433
|
+
Four properties, all easy to get wrong:
|
|
434
|
+
|
|
435
|
+
1. **It is the engine's transition, not the worker's.** No agent reads this
|
|
436
|
+
block. A worker cannot opt in or out.
|
|
437
|
+
2. **It is per step and per run.** The `builder` escalating does not change
|
|
438
|
+
what `planner` or `reviewer` are offered as.
|
|
439
|
+
3. **It never rewrites the run's stored modifier.** The instance still says
|
|
440
|
+
`modifier = "standard"`. Only that one step's offer moved.
|
|
441
|
+
4. **It is a no-op on a run that is already at the target grade.** A `deep` run
|
|
442
|
+
whose builder escalates to `deep` just keeps re-offering `build:deep`.
|
|
443
|
+
|
|
444
|
+
The order carries a marker, `order.escalated = true`, so a reader can tell an
|
|
445
|
+
escalated re-offer from an ordinary one.
|
|
446
|
+
|
|
447
|
+
Escalation moves one offer. It never rewrites the run's stored modifier. There
|
|
448
|
+
is a separate mechanism that does, and it is the only one.
|
|
449
|
+
|
|
450
|
+
### 8a. The modifier bind — the engine's only post-start writer
|
|
451
|
+
|
|
452
|
+
A workflow definition can declare that one artifact **carries** the run's
|
|
453
|
+
modifier. When that artifact is accepted, the engine writes its value onto the
|
|
454
|
+
run instance. The declaration lives on the produce:
|
|
455
|
+
|
|
456
|
+
```yaml
|
|
457
|
+
modifiers: [express, standard, deep]
|
|
458
|
+
|
|
459
|
+
steps:
|
|
460
|
+
- name: init
|
|
461
|
+
executor: command
|
|
462
|
+
capabilities: [init]
|
|
463
|
+
command: >-
|
|
464
|
+
value="$(owenloop util modifier-init --default standard)" &&
|
|
465
|
+
node -e 'console.log("##owenloop:payload##" +
|
|
466
|
+
JSON.stringify({value: process.argv[1]}))' "$value"
|
|
467
|
+
produces:
|
|
468
|
+
- name: modifier
|
|
469
|
+
bind: { to: modifier, from: payload.value }
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
Read: *when `modifier` is accepted, set the run's modifier to the `payload.value`
|
|
473
|
+
field of the accepted value.* The full authoring grammar — the short form, the
|
|
474
|
+
`meta.<key>` target family, the dot-path rules — is in
|
|
475
|
+
[`docs/authoring.md`](authoring.md#bind--write-an-accepted-artifact-into-run-state).
|
|
476
|
+
What follows is what the mechanism *means* for routing.
|
|
477
|
+
|
|
478
|
+
Five properties, in the order they matter:
|
|
479
|
+
|
|
480
|
+
1. **A `modifier` bind requires the def to declare `modifiers:`.** Without it,
|
|
481
|
+
loading the definition fails: `step '<step>' produce '<stem>' binds modifier
|
|
482
|
+
but workflow '<def>' declares no modifiers:` (`src/defs.ts`). A definition may
|
|
483
|
+
bind `modifier` at most once — a second one is
|
|
484
|
+
`workflow '<def>' binds modifier more than once`. The only other legal target
|
|
485
|
+
family is `bind: meta.<key>`, which writes non-routing instance metadata and
|
|
486
|
+
never touches capability composition. Binding is available on singleton and
|
|
487
|
+
per-element (map) produces; it is refused on collection produces and on
|
|
488
|
+
`calls:` outcomes.
|
|
489
|
+
|
|
490
|
+
2. **The engine is the only writer.** No agent, step, worker, judge, or human
|
|
491
|
+
writes the run's modifier directly. The write goes through one private engine
|
|
492
|
+
method, `applyArtifactBind` (`src/engine.ts`), into one store method,
|
|
493
|
+
`setWorkflowRouting` (`src/store.ts`) — and those are the only two production
|
|
494
|
+
call sites of that store method under `src/`. There is no verb, flag, or MCP
|
|
495
|
+
call that sets it. `--modifier` at `start_run` supplies the initial value and
|
|
496
|
+
nothing after that.
|
|
497
|
+
|
|
498
|
+
3. **The write happens inside the artifact-acceptance transaction.** The
|
|
499
|
+
modifier changes **if and only if** the bound artifact reaches green — by a
|
|
500
|
+
producer commit on a produce with no judges, by the last judge's approval, or
|
|
501
|
+
by a human `green`. All three branches run inside the same `store.tx()` that
|
|
502
|
+
writes the artifact, so acceptance and the routing write commit together or
|
|
503
|
+
neither happens. A submission still waiting on judges has synchronized
|
|
504
|
+
nothing. A value outside the declared set is refused before its accepted value
|
|
505
|
+
or green transition is written: a producer commit records the artifact as
|
|
506
|
+
`rejected`, comes back `schema-rejected`, and burns a schema attempt; a human
|
|
507
|
+
`green` throws `ModifierRefusalError` — the same refusal `start_run` uses.
|
|
508
|
+
|
|
509
|
+
4. **The lever for changing it is rejecting the bound artifact with
|
|
510
|
+
`requested:`.**
|
|
511
|
+
|
|
512
|
+
```bash
|
|
513
|
+
owenloop reject <wf> modifier --by planner --text "this needs deep review" \
|
|
514
|
+
--requested deep
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
The engine validates `deep` against the definition's declared `modifiers:` at
|
|
518
|
+
**reject** time, not later: an undeclared value throws
|
|
519
|
+
`ModifierRefusalError` and nothing is written at all. A `--requested` on an
|
|
520
|
+
artifact that is not bound to `modifier` is refused outright. The validated
|
|
521
|
+
value is then carried on the rejection's reason entry, and reaches the
|
|
522
|
+
producer's next order as `owes[].reasons[].requested` — and, for a command
|
|
523
|
+
step, through `OWENLOOP_FEEDBACK` (see
|
|
524
|
+
[`docs/bundles.md`](bundles.md#rejection-feedback-and-modifier-context)).
|
|
525
|
+
`requested` is a **request to the producer**, not a write. The producer
|
|
526
|
+
re-emits; only the acceptance of that new value moves the run.
|
|
527
|
+
|
|
528
|
+
**Who may pull the lever is the ordinary authority rule, unchanged.** `human`
|
|
529
|
+
and `engine` may always reject. A judge step may reject only the stem named in
|
|
530
|
+
its own `judges:` marker. Any other step may reject only an artifact it
|
|
531
|
+
declares in `consumes:`. So a planner that is meant to ask for a different
|
|
532
|
+
grade must declare `consumes: [modifier]` in the definition; a planner with no
|
|
533
|
+
such edge cannot reject it and can only say so in its plan document.
|
|
534
|
+
|
|
535
|
+
5. **The record of what changed is the artifact history.** Each accepted sync
|
|
536
|
+
writes exactly one artifact event: `action: bound`, `actor: engine`,
|
|
537
|
+
`version: 0`, `metadata: { from, to }`, where `from` is `null` when the target
|
|
538
|
+
had no prior value. `Store.getArtifactHistory(workflow, path)` surfaces those
|
|
539
|
+
in its artifact-level `events` bucket. The event is idempotent by
|
|
540
|
+
construction, keyed on the accepted artifact version, so one acceptance can
|
|
541
|
+
only ever produce one row. The second half of the record is per-offer:
|
|
542
|
+
`order.modifier` is stamped on every order, so an order always says which
|
|
543
|
+
grade that firing actually ran under.
|
|
544
|
+
|
|
545
|
+
**What the binding does not do.** It is ordinary dataflow, not a hidden reroute.
|
|
546
|
+
The engine reads the run's current modifier at tick time and composes each offer
|
|
547
|
+
from it, so claims already in flight finish under the modifier stamped on their
|
|
548
|
+
own orders, and only offers composed *after* the sync see the new value. A
|
|
549
|
+
capability-bearing step that is not downstream of the bound artifact can
|
|
550
|
+
therefore be offered on the old grade. `lintDef` warns about exactly that:
|
|
551
|
+
`step '<name>' declares capabilities (…) but is not downstream of artifact
|
|
552
|
+
'<path>' bound to modifier`. If a step must run at the synchronized grade, wire
|
|
553
|
+
the dependency explicitly — make it consume the bound artifact.
|
|
554
|
+
|
|
555
|
+
**Escalation and the bind are separate mechanisms over related state.**
|
|
556
|
+
Escalation is derived per offer from a reject count and leaves the stored
|
|
557
|
+
modifier alone. The bind rewrites the stored modifier; that value can determine
|
|
558
|
+
whether an otherwise eligible escalation target differs and therefore whether
|
|
559
|
+
escalation applies. A run can do both. An escalated offer stamps the escalation
|
|
560
|
+
target on `order.modifier` for that one firing; the next ordinary offer composes
|
|
561
|
+
from the run's stored value again — whatever the last accepted bind left there.
|
|
562
|
+
|
|
563
|
+
**Command producers: bind the payload, not the receipt.** A command step's
|
|
564
|
+
accepted artifact value is the whole `CommandReceipt`. The short form
|
|
565
|
+
`bind: modifier` is shorthand for `{to: modifier, from: modifier}`. A
|
|
566
|
+
`CommandReceipt` has no top-level `modifier` key, so that derived path does
|
|
567
|
+
not resolve and the submit is refused. Have the command emit a payload marker —
|
|
568
|
+
`##owenloop:payload##{"value":"deep"}` — and bind `from: payload.value`.
|
|
569
|
+
|
|
570
|
+
> **Not shipped.** The routing plan also calls for a hub-side routing alert of
|
|
571
|
+
> kind `modifier-changed`, raised on each sync so an operator sees it. It exists
|
|
572
|
+
> in neither `owenloop` nor `owenloop-service` today. When it lands it is a
|
|
573
|
+
> notification for operator attention — the artifact history above stays the
|
|
574
|
+
> system of record, and an alert must never be read as one.
|
|
575
|
+
|
|
576
|
+
---
|
|
577
|
+
|
|
578
|
+
## 9. When nobody is certified — the rule that is changing
|
|
579
|
+
|
|
580
|
+
This is the single line that has caused more confusion than everything else in
|
|
581
|
+
this document combined. It is worth reading twice.
|
|
582
|
+
|
|
583
|
+
**The situation:** a run is started with `--modifier express`. The `builder`
|
|
584
|
+
step composes to `build:express`. The hub looks in `capability_routes` and
|
|
585
|
+
finds **no live crew certified for `build:express`.**
|
|
586
|
+
|
|
587
|
+
### 9a. The OLD rule (what a current hub does)
|
|
588
|
+
|
|
589
|
+
The hub falls back to **name matching**: it offers the job to any crew
|
|
590
|
+
certified for anything whose name part is `build` — so the crew certified for
|
|
591
|
+
plain `build` claims it.
|
|
592
|
+
|
|
593
|
+
Why that is bad: the claiming shift receives `order.capabilities =
|
|
594
|
+
['build:express']`, finds no `build:express` row in its `roster`,
|
|
595
|
+
falls back to its bare `build` row, and runs on that model. The run believes it
|
|
596
|
+
got express service. It actually got whatever the generic build row happens to
|
|
597
|
+
be. Nothing failed, nothing was logged loudly, and the operator has no signal.
|
|
598
|
+
|
|
599
|
+
It converts the fact *"no shift is serving express right now"* into the
|
|
600
|
+
different fact *"the operator accepted a different grade of service."* Those
|
|
601
|
+
are not the same thing and the system had no business equating them.
|
|
602
|
+
|
|
603
|
+
### 9b. The NEW rule (what is being built)
|
|
604
|
+
|
|
605
|
+
**An unbound compound holds.** The hub keeps the mode at `exact`, so the order
|
|
606
|
+
simply waits until a crew certified for `build:express` clocks in. It does not
|
|
607
|
+
degrade to a generic worker.
|
|
608
|
+
|
|
609
|
+
**And the operator is told.** The hub writes a routing alert (kind
|
|
610
|
+
`binding-gap`) naming the capability that has no certified crew.
|
|
611
|
+
|
|
612
|
+
**Holding is not failure.** A held order is not dead. It is waiting. The
|
|
613
|
+
existing stall-notification system covers the case where a run sits too long,
|
|
614
|
+
and a crew that was restarted picks the work up when it comes back. There is no
|
|
615
|
+
built-in timer that silently downgrades the job.
|
|
616
|
+
|
|
617
|
+
The old behavior had a 15-minute escalation-fallback window baked in. That is
|
|
618
|
+
being removed. If an operator wants a timed fallback, they configure it; the
|
|
619
|
+
system does not assume it.
|
|
620
|
+
|
|
621
|
+
---
|
|
622
|
+
|
|
623
|
+
## 10. Reroute rules — saying "yes, substitute" on purpose
|
|
624
|
+
|
|
625
|
+
*(The engine half is in `owenloop`, the hub half is in `owenloop-service`, and
|
|
626
|
+
the CLI surface is `owenloop routing rule` — see
|
|
627
|
+
[Routing](cli.md#routing) in the CLI reference. The MCP surface follows.)*
|
|
628
|
+
|
|
629
|
+
Holding is the right default, but sometimes the operator genuinely does want a
|
|
630
|
+
substitution — "if nobody is serving `build:express` right now, `build:standard`
|
|
631
|
+
is fine." Section 9's rule makes that a decision the operator states, instead of
|
|
632
|
+
something the hub assumes.
|
|
633
|
+
|
|
634
|
+
A **reroute rule** is exactly that statement:
|
|
635
|
+
|
|
636
|
+
```
|
|
637
|
+
build:express -> build:standard
|
|
638
|
+
```
|
|
639
|
+
|
|
640
|
+
How it works, mechanically:
|
|
641
|
+
|
|
642
|
+
1. The hub composes the offer as usual and finds `build:express` has no live
|
|
643
|
+
binding.
|
|
644
|
+
2. The hub consults the operator's reroute rules and finds a target,
|
|
645
|
+
`build:standard`, that *does* have a live binding.
|
|
646
|
+
3. The hub hands the engine a **rewrite**: `{ 'build:express': 'build:standard' }`.
|
|
647
|
+
4. The engine **substitutes the string**. The order goes out as
|
|
648
|
+
`build:standard`, and carries `reroutedFrom: ['build:express']`.
|
|
649
|
+
5. The hub writes a routing alert (kind `reroute`) recording that it happened.
|
|
650
|
+
|
|
651
|
+
**Why substitute the string rather than just loosen the match?** Because the
|
|
652
|
+
claiming shift resolves its model from `order.capabilities`. If the hub merely
|
|
653
|
+
widened the match, the shift would receive `build:express`, find no row for it,
|
|
654
|
+
and fall back to its bare `build` row — the wrong model, which is the exact bug
|
|
655
|
+
section 9a describes. Substituting means the shift receives `build:standard` and
|
|
656
|
+
resolves *standard's* model, which is what the operator asked for.
|
|
657
|
+
|
|
658
|
+
**Why two fields on the order?** A rerouted order has two simultaneously true
|
|
659
|
+
answers to "which capability is this?"
|
|
660
|
+
|
|
661
|
+
- `capabilities` — the capability **being served**. This is what the shift
|
|
662
|
+
resolves its model against.
|
|
663
|
+
- `reroutedFrom` — the capability the definition **asked for**.
|
|
664
|
+
|
|
665
|
+
`reroutedFrom` is absent on every ordinary offer, so its presence alone tells a
|
|
666
|
+
reader the order is not running on what its definition requested. A single field
|
|
667
|
+
could only ever carry one of the two facts, and an operator asking "why did this
|
|
668
|
+
run on Opus?" would have no way back to "because we asked for express."
|
|
669
|
+
|
|
670
|
+
**The run's stored modifier is never touched by a reroute.** Re-reading the run
|
|
671
|
+
record still shows the grade of service that was requested. Only the offer
|
|
672
|
+
moved.
|
|
673
|
+
|
|
674
|
+
**Chains are resolved by the hub, not the engine.** If `a -> b` and `b -> c`,
|
|
675
|
+
the hub walks the chain and hands the engine the final answer. The engine
|
|
676
|
+
performs exactly one substitution and never looks a target up again, so a cycle
|
|
677
|
+
is impossible there rather than merely bounded.
|
|
678
|
+
|
|
679
|
+
### How an operator states and inspects all of this
|
|
680
|
+
|
|
681
|
+
The rules and the alerts are two separate command surfaces on one hub org — see
|
|
682
|
+
[Routing](cli.md#routing) in the CLI reference for flags, output shape and exit
|
|
683
|
+
codes.
|
|
684
|
+
|
|
685
|
+
| what you want | command |
|
|
686
|
+
|---|---|
|
|
687
|
+
| write the rule `build:express -> build:standard` | `owenloop routing rule add build:express build:standard` |
|
|
688
|
+
| put a rule ahead of the ones already there | `owenloop routing rule add build:express build --position 0` |
|
|
689
|
+
| see the rules in the order the hub tries them | `owenloop routing rule list` |
|
|
690
|
+
| take one rule back | `owenloop routing rule rm build:express build:standard` |
|
|
691
|
+
| see every hold, reroute, wait and fallback org-wide | `owenloop routing alerts` |
|
|
692
|
+
| see one run's routing timeline | `owenloop routing show <workflow>` |
|
|
693
|
+
|
|
694
|
+
**Three cautions the command names do not carry on their own.**
|
|
695
|
+
|
|
696
|
+
1. **A reroute rule is not a binding.** `routing rule add` writes a
|
|
697
|
+
`capability_reroutes` row, which names no crew and grants nobody access.
|
|
698
|
+
`capability bind` writes a `capability_routes` row, which does. A reroute
|
|
699
|
+
only reaches a crew if its **target** capability has a live binding of its
|
|
700
|
+
own, so adding a rule cannot by itself widen who may claim work.
|
|
701
|
+
2. **`routing rule list` order is meaning, not presentation.** Rows are grouped
|
|
702
|
+
by source capability and ordered by ascending `position` — the first row for
|
|
703
|
+
a capability is the first target the hub attempts.
|
|
704
|
+
3. **Removing the last rule for a capability restores holding.** With no rule
|
|
705
|
+
left, an unbound compound waits again, exactly as section 9b describes. The
|
|
706
|
+
CLI prints `remainingTargets: []` and says so on stderr.
|
|
707
|
+
|
|
708
|
+
---
|
|
709
|
+
|
|
710
|
+
## 11. The mistakes we keep making
|
|
711
|
+
|
|
712
|
+
Each of these has actually happened. Each has a one-line correction.
|
|
713
|
+
|
|
714
|
+
| Mistake | Correction |
|
|
715
|
+
|---|---|
|
|
716
|
+
| "Name the crew after the job it performs — call the crew that builds `build`." | A crew is named after the **team**, never after the job. When `build` is both a capability and a crew name the two lookups become invisible, and the reader cannot tell the hub-side routing table (`capability_routes`) from the shift-side rate card (`roster`). Name crews `anthropic` and `openai`. |
|
|
717
|
+
| "The capability says which model to use." | It says which *job*. The model comes from the shift's local `settings.json`, at the very last step. |
|
|
718
|
+
| "`build:deep` belongs to the openai crew." | No — `build:deep` is *certified to* the `openai` crew. Certify a second crew for it and both are eligible. Nothing owns it. |
|
|
719
|
+
| "A shift declares its capabilities." | A shift now advertises raw merged-roster keys as an offer filter, but that never grants authority. Authority remains crew-derived, and the worker's refusal backstop is unchanged. Today's hub ignores the field; the intersect ships separately. |
|
|
720
|
+
| "The shift's positional crews decide an agent worker's roster." | No. They only advertise worker → hub `serve_crews`; the hub-stamped `order.crews` list resolves each capability-bearing order's roster sequence. |
|
|
721
|
+
| "The shift that is clocked in has no rate for `build:deep`, so serve it something else." | Do not serve it at all. Certify the crew that *can* do it. That is what the binding is for. |
|
|
722
|
+
| "`--modifier` defaults to standard." | Omitting it means **no modifier**. Steps are offered on bare authored capabilities. |
|
|
723
|
+
| "A modifier means 'more effort'." | To the engine it is an opaque string. All meaning lives in the shift's `roster` map. |
|
|
724
|
+
| "A planner can decide the run needs to go deeper." | Only where the definition declares `modifiers:`, binds an artifact to `modifier`, and the planner **consumes** that artifact. Then it rejects it with `--requested deep`, the producer re-emits, and the **engine** — never the planner — writes the run's modifier when that artifact is accepted. With no such wiring the planner can still only say so in its plan document (section 8a). |
|
|
725
|
+
| "The bind means my step writes the run's modifier." | No step writes it. The engine does, inside the acceptance transaction of the bound artifact. `--requested` on a reject is a validated *request* to that artifact's producer, not a write — and it is refused outright on any artifact that is not bound to `modifier`. |
|
|
726
|
+
| "Escalation upgrades the run." | It re-offers **one step**, temporarily. The run's stored modifier is untouched. |
|
|
727
|
+
| "If nobody serves the compound, close enough is fine." | Not any more. It holds and alerts. Substitution is something the operator configures on purpose (section 10). |
|
|
728
|
+
| "Two harnesses in one crew gives me control over which model runs." | It gives you *either* model. First claim wins. Use separate crews when you need a guarantee. |
|
|
729
|
+
|
|
730
|
+
---
|
|
731
|
+
|
|
732
|
+
## 12. One-screen summary
|
|
733
|
+
|
|
734
|
+
```
|
|
735
|
+
delivery.yaml steps: [{ name: builder, capabilities: [build] }]
|
|
736
|
+
|
|
|
737
|
+
owenloop start --modifier standard (initial hint; a bind may later change it)
|
|
738
|
+
|
|
|
739
|
+
bound artifact accepted -> engine syncs the run modifier (audited in its history)
|
|
740
|
+
|
|
|
741
|
+
engine composes build + deep -> "build:deep"
|
|
742
|
+
|
|
|
743
|
+
hub reads capability_routes: build:deep -> crew "openai"
|
|
744
|
+
|
|
|
745
|
+
hub derives caller set from the asking shift's crew memberships
|
|
746
|
+
shift sends serve_crews plus raw merged-roster serve_capabilities
|
|
747
|
+
(today's hub ignores serve_capabilities; the intersect ships separately)
|
|
748
|
+
|
|
|
749
|
+
match: exact -> only crews certified for "build:deep" may claim
|
|
750
|
+
|
|
|
751
|
+
the openai-1 shift claims; order.capabilities = ["build:deep"]
|
|
752
|
+
order.crews = ["openai"]
|
|
753
|
+
|
|
|
754
|
+
agent resolves the stamped crew roster:
|
|
755
|
+
"build:deep": [{ harness: codex, model: gpt-5.6-terra, effort: xhigh }]
|
|
756
|
+
|
|
|
757
|
+
the selected candidate spawns that model at that effort
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
If the lookup at step 3 finds nobody: the order **holds** and an alert is
|
|
761
|
+
written. If the operator has configured a reroute rule, the hub substitutes the
|
|
762
|
+
target capability and records `reroutedFrom` on the order.
|