owenloop 0.5.7 → 0.5.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/README.md +3 -6
- 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 +39 -25
- package/dist/packages/work/src/agent/loop.js +102 -50
- package/dist/packages/work/src/bundle/types.d.ts +3 -3
- package/dist/packages/work/src/exec/loop.js +37 -15
- package/dist/packages/work/src/harness/child-env.js +4 -5
- package/dist/packages/work/src/harness/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/types.d.ts +3 -3
- package/dist/packages/work/src/roles/agent-run.js +48 -42
- package/dist/packages/work/src/roles/sessions.d.ts +3 -2
- package/dist/packages/work/src/roles/sessions.js +9 -2
- package/dist/packages/work/src/roles/settings.js +1 -1
- package/dist/packages/work/src/settings/roster.d.ts +21 -0
- package/dist/packages/work/src/settings/roster.js +80 -0
- package/dist/packages/work/src/settings/settings.d.ts +12 -24
- package/dist/packages/work/src/settings/settings.js +17 -35
- package/dist/packages/work/src/shift/runtime.js +2 -10
- package/dist/packages/work/src/shift/spawn.d.ts +6 -53
- package/dist/packages/work/src/shift/spawn.js +28 -66
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +3 -4
- package/dist/src/capabilities.d.ts +44 -0
- package/dist/src/capabilities.js +38 -0
- package/dist/src/cli.d.ts +1 -0
- package/dist/src/cli.js +460 -5
- package/dist/src/config-dir.d.ts +13 -18
- package/dist/src/config-dir.js +15 -23
- package/dist/src/credentials.d.ts +1 -1
- package/dist/src/credentials.js +1 -1
- package/dist/src/crypto/records.d.ts +1 -0
- package/dist/src/crypto/records.js +6 -0
- package/dist/src/crypto/trust-roots.d.ts +2 -2
- package/dist/src/crypto/trust-roots.js +2 -2
- package/dist/src/engine.d.ts +14 -0
- package/dist/src/engine.js +21 -13
- package/dist/src/global-config.d.ts +4 -7
- package/dist/src/global-config.js +4 -7
- package/dist/src/hub.d.ts +207 -5
- package/dist/src/hub.js +263 -3
- package/dist/src/index.d.ts +2 -2
- package/dist/src/index.js +1 -1
- package/dist/src/schemas/index.d.ts +8 -0
- package/dist/src/schemas/order.v1.schema.json +6 -1
- package/dist/src/store/pre-commit-verifier.js +1 -1
- package/dist/src/types.d.ts +24 -4
- package/dist/src/work-settings.d.ts +2 -4
- package/dist/src/work-settings.js +2 -4
- package/docs/agent-runner.md +2 -2
- package/docs/bundles.md +3 -1
- package/docs/cli.md +295 -101
- package/docs/crypto.md +14 -14
- package/docs/routing.md +607 -0
- package/docs/shift-logs.md +22 -6
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
package/docs/routing.md
ADDED
|
@@ -0,0 +1,607 @@
|
|
|
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.
|
|
15
|
+
|
|
16
|
+
Section 9 (**When nobody is certified**) describes a rule that is CHANGING.
|
|
17
|
+
Both the old rule and the new rule are stated, and it is marked which is which,
|
|
18
|
+
because a deployment running an older hub still does the old thing.
|
|
19
|
+
|
|
20
|
+
Section 10 (**Reroute rules**) describes a feature whose engine, hub and CLI
|
|
21
|
+
halves are now in place; the MCP surface is not. It is marked as such.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 1. The four words
|
|
26
|
+
|
|
27
|
+
The single biggest source of confusion is the word **capability**. It sounds
|
|
28
|
+
like a property of a machine — "this box can run Opus." It is not that at all.
|
|
29
|
+
|
|
30
|
+
Use this mapping instead. It is exact, not a loose analogy.
|
|
31
|
+
|
|
32
|
+
| Term | Think of it as | Who writes it | Where it lives |
|
|
33
|
+
|---|---|---|---|
|
|
34
|
+
| **capability** | a **job posting** | the workflow author | the workflow definition file (`delivery.yaml`) |
|
|
35
|
+
| **modifier** | the **grade on the posting** | the person starting the run | chosen once at `start_run`, stored on the instance |
|
|
36
|
+
| **crew** | a **team certified for that posting** | the hub operator | the hub's `capability_routes` table |
|
|
37
|
+
| **shift** | a **team member clocking in** | whoever runs the machine | a local `settings.json` on that machine |
|
|
38
|
+
|
|
39
|
+
Read as one sentence:
|
|
40
|
+
|
|
41
|
+
> A **workflow definition** posts a job (`build`). The person starting the run
|
|
42
|
+
> stamps a grade on it (`deep`), making the posting `build:deep`. The **hub**
|
|
43
|
+
> looks up which **crews** are certified for `build:deep`. A **shift** — one
|
|
44
|
+
> member of a certified crew, currently clocked in — takes the job and decides,
|
|
45
|
+
> from its own local settings, which model and effort to run it on.
|
|
46
|
+
|
|
47
|
+
Four things follow from that sentence, and all four are places people get it
|
|
48
|
+
wrong:
|
|
49
|
+
|
|
50
|
+
1. **A capability never names a model.** `build` does not mean "Opus." It means
|
|
51
|
+
"somebody who does building." The model is chosen at the very last step, by
|
|
52
|
+
the shift, from its own settings file.
|
|
53
|
+
2. **A capability never names a machine.** Nothing in the definition or the hub
|
|
54
|
+
knows what hardware or CLI exists.
|
|
55
|
+
3. **Certifying a crew is a promise about every member.** Binding `build:deep`
|
|
56
|
+
to the crew `openai` says: *every shift that serves the openai crew can do
|
|
57
|
+
deep build work.* If one member cannot, the binding is wrong.
|
|
58
|
+
4. **The mapping is many-to-many, both directions.** One capability can be
|
|
59
|
+
bound to several crews. One crew can be bound to several capabilities. One
|
|
60
|
+
shift can serve several crews (`owenloop shift start anthropic openai`
|
|
61
|
+
takes a list). On the staging hub every shift serves exactly one crew, so
|
|
62
|
+
this shows the shape of the argument rather than a shift that exists today.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 2. The three vocabularies, precisely
|
|
67
|
+
|
|
68
|
+
There are exactly three kinds of capability string, and they are different
|
|
69
|
+
things. Mixing them up is the second biggest source of confusion.
|
|
70
|
+
|
|
71
|
+
**Authored capability** — what a workflow step declares. Never contains a
|
|
72
|
+
colon.
|
|
73
|
+
|
|
74
|
+
```yaml
|
|
75
|
+
- name: builder
|
|
76
|
+
capabilities: [build] # <- authored capability
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Modifier** — one word, chosen once per run. The engine attaches *no meaning*
|
|
80
|
+
to it. `deep` is not "more" than `express` as far as any code is concerned;
|
|
81
|
+
they are just two different strings. A definition declares which ones it
|
|
82
|
+
accepts:
|
|
83
|
+
|
|
84
|
+
```yaml
|
|
85
|
+
modifiers: [express, standard, deep]
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Compound capability** — an authored capability with a modifier glued on by a
|
|
89
|
+
colon: `build:deep`. **Nobody writes this by hand in a workflow definition.**
|
|
90
|
+
It is composed by the engine at the moment an order is offered, by
|
|
91
|
+
`composeCapabilities(step.capabilities, modifier)` in `src/capabilities.ts`.
|
|
92
|
+
|
|
93
|
+
A run with no modifier composes to the bare authored capability. `build` stays
|
|
94
|
+
`build`. There is no default modifier — omitting `--modifier` does not mean
|
|
95
|
+
`standard`, it means *no modifier at all*.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 3. Where each fact physically lives
|
|
100
|
+
|
|
101
|
+
Three files, three different owners, three different machines potentially.
|
|
102
|
+
|
|
103
|
+
### 3a. The workflow definition — "what job is this?"
|
|
104
|
+
|
|
105
|
+
A `.yaml` in a bundle, e.g. `owenloop-delivery/workflows/delivery.yaml`.
|
|
106
|
+
|
|
107
|
+
```yaml
|
|
108
|
+
modifiers: [express, standard, deep]
|
|
109
|
+
|
|
110
|
+
steps:
|
|
111
|
+
- name: planner
|
|
112
|
+
capabilities: [wise]
|
|
113
|
+
- name: builder
|
|
114
|
+
capabilities: [build]
|
|
115
|
+
- name: reviewer
|
|
116
|
+
capabilities: [review]
|
|
117
|
+
- name: provisioner
|
|
118
|
+
capabilities: [utility]
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
This file names jobs. It names no models, no crews, no machines.
|
|
122
|
+
|
|
123
|
+
### 3b. The hub's `capability_routes` table — "who is certified?"
|
|
124
|
+
|
|
125
|
+
A table inside the hub, one row per `(capability string, crew)` pair. Written
|
|
126
|
+
with `owenloop capability bind <capability> <crew>`.
|
|
127
|
+
|
|
128
|
+
The staging hub's current rows are exactly these sixteen:
|
|
129
|
+
|
|
130
|
+
| capability | crew |
|
|
131
|
+
|---|---|
|
|
132
|
+
| `wise` | `anthropic` |
|
|
133
|
+
| `wise:express` | `anthropic` |
|
|
134
|
+
| `wise:standard` | `anthropic` |
|
|
135
|
+
| `wise:deep` | `anthropic` |
|
|
136
|
+
| `build` | `openai` |
|
|
137
|
+
| `build:express` | `openai` |
|
|
138
|
+
| `build:standard` | `openai` |
|
|
139
|
+
| `build:deep` | `openai` |
|
|
140
|
+
| `review` | `openai` |
|
|
141
|
+
| `review:express` | `openai` |
|
|
142
|
+
| `review:standard` | `openai` |
|
|
143
|
+
| `review:deep` | `openai` |
|
|
144
|
+
| `utility` | `openai` |
|
|
145
|
+
| `utility:express` | `openai` |
|
|
146
|
+
| `utility:standard` | `openai` |
|
|
147
|
+
| `utility:deep` | `openai` |
|
|
148
|
+
|
|
149
|
+
The live table gives the `anthropic` crew one job family and its modifiers:
|
|
150
|
+
the four `wise` strings. It gives the `openai` crew three job families and
|
|
151
|
+
their modifiers: `build`, `review`, and `utility`. A crew name says which
|
|
152
|
+
team; a capability says which job. Nothing in `anthropic` or `openai` tells
|
|
153
|
+
you what job it does, and that is correct — the crew name is not supposed to.
|
|
154
|
+
|
|
155
|
+
A capability can still be certified to a crew whose name has nothing to do with
|
|
156
|
+
the job. If an operator wanted deep build work on Anthropic models, the
|
|
157
|
+
operator would run:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
owenloop capability bind build:deep anthropic
|
|
161
|
+
owenloop capability unbind build:deep openai
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The *job* is still a build job. Only the *team* changes.
|
|
165
|
+
|
|
166
|
+
These are two commands, not one. `capability bind` on an already-bound
|
|
167
|
+
capability **adds** a crew; it never replaces one. With only the bind,
|
|
168
|
+
`build:deep` would be certified to both `openai` and `anthropic`, and
|
|
169
|
+
which crew's shift claims a given order would be a race. The unbind is what
|
|
170
|
+
makes it a move. This is verified by `src/cli.ts:5079` and independently by
|
|
171
|
+
`docs/authoring.md:254`.
|
|
172
|
+
|
|
173
|
+
That hypothetical move also needs a rate-card change. The shift first looks
|
|
174
|
+
for an exact `build:deep` row and then may fall back to a bare `build` row.
|
|
175
|
+
The `anthropic` card shown here has neither row, so after the rebind it would
|
|
176
|
+
refuse the order with `unresolvable-capability`, and the hub would re-offer it.
|
|
177
|
+
If the card had a bare `build` row, the shift would run that row's potentially
|
|
178
|
+
different model and effort instead. The operator must add an intentional
|
|
179
|
+
`build:deep` row to the `anthropic` card as part of the same move.
|
|
180
|
+
|
|
181
|
+
### 3c. The crew roster — “what can this machine run?”
|
|
182
|
+
|
|
183
|
+
“Roster” in this document means the **crew roster** used for capability
|
|
184
|
+
routing, never the trust roster of signed grants in `~/.owenloop/roster/`.
|
|
185
|
+
A machine's global fallback lives under the `roster` key in
|
|
186
|
+
`~/.owenloop/settings.json`; a named crew's stronger layer is
|
|
187
|
+
`~/.owenloop/crews/<crew>.json`. Both files use the same top-level shape:
|
|
188
|
+
|
|
189
|
+
```json
|
|
190
|
+
{
|
|
191
|
+
"roster": {
|
|
192
|
+
"wise:deep": [
|
|
193
|
+
{ "harness": "claude-code", "model": "claude-fable-5", "effort": "xhigh" },
|
|
194
|
+
{ "harness": "codex", "model": "gpt-5.6-sol", "effort": "xhigh" }
|
|
195
|
+
],
|
|
196
|
+
"wise": [
|
|
197
|
+
{ "harness": "claude-code", "model": "claude-opus-5", "effort": "high" }
|
|
198
|
+
]
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Every value is a non-empty ordered candidate array. The stronger crew layer
|
|
204
|
+
replaces a capability's full array from the machine-global layer; arrays are
|
|
205
|
+
never combined. Exact composed capability lookup runs before bare-name lookup
|
|
206
|
+
across all offered capabilities. The first candidate whose harness is
|
|
207
|
+
registered wins, unless a step's `x.harness.id` requires a different harness.
|
|
208
|
+
That mismatch is an `incompatible-harness-policy` release; no registered
|
|
209
|
+
candidate is `unresolvable-capability`.
|
|
210
|
+
|
|
211
|
+
### 4. The four things a shift is configured with
|
|
212
|
+
|
|
213
|
+
A shift start command names its crews, credentials, display identity, and
|
|
214
|
+
state directory. It no longer carries an operator-selected harness or a
|
|
215
|
+
per-shift config directory. The shift passes its positional crews to agent
|
|
216
|
+
children internally; they try matching merged crew rosters in command-line
|
|
217
|
+
order. This is an interim Phase-1 rule until the hub stamps matched crews on
|
|
218
|
+
the order.
|
|
219
|
+
|
|
220
|
+
| Name | What it selects |
|
|
221
|
+
|---|---|
|
|
222
|
+
| **crew** (positional) | which crew rosters the shift serves |
|
|
223
|
+
| **`--as`** | which stored credential to authenticate with |
|
|
224
|
+
| **`--name`** | a display label for this shift |
|
|
225
|
+
| **`--state-dir`** | local socket and child-state storage |
|
|
226
|
+
|
|
227
|
+
Use `owenloop roster show [crew]` to see each selected candidate and the
|
|
228
|
+
layer that supplied it. `owenloop doctor` reports the same layers and whether
|
|
229
|
+
their candidate harnesses are registered.
|
|
230
|
+
|
|
231
|
+
## 5. What actually happens when an order is offered
|
|
232
|
+
|
|
233
|
+
Here is one order, end to end, in order.
|
|
234
|
+
|
|
235
|
+
**Step 1 — a human starts a run.**
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
owenloop start delivery --modifier deep \
|
|
239
|
+
--provide proposal='{"text":"..."}' \
|
|
240
|
+
--provide target='{"path":"/Users/alex/code/owenloop"}'
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
The hub creates an instance and stores `modifier = "deep"` on it. **This value
|
|
244
|
+
is set once and never changes for the life of the run.** There is no verb that
|
|
245
|
+
updates it.
|
|
246
|
+
|
|
247
|
+
**Step 2 — a shift asks for work.**
|
|
248
|
+
|
|
249
|
+
The `openai-1` shift calls the hub verb `whats_next`, authenticating as
|
|
250
|
+
account `shift-openai-1`.
|
|
251
|
+
|
|
252
|
+
**Step 3 — the hub works out what this caller can do.**
|
|
253
|
+
|
|
254
|
+
The hub does *not* read anything the shift sent about its abilities. Instead:
|
|
255
|
+
|
|
256
|
+
- it looks up which crews the account `shift-openai-1` belongs to;
|
|
257
|
+
- it reads every `capability_routes` row for those crews;
|
|
258
|
+
- the resulting list of capability strings is the caller's capability set.
|
|
259
|
+
|
|
260
|
+
The function is `listCapabilitiesForCrews(storage, memberCrewIds)`. For the
|
|
261
|
+
`openai-1` shift on staging that yields this set:
|
|
262
|
+
|
|
263
|
+
```
|
|
264
|
+
['build', 'build:deep', 'build:express', 'build:standard',
|
|
265
|
+
'review', 'review:deep', 'review:express', 'review:standard',
|
|
266
|
+
'utility', 'utility:deep', 'utility:express', 'utility:standard']
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
The strings are shown alphabetically for readability; their order is not
|
|
270
|
+
significant.
|
|
271
|
+
|
|
272
|
+
This is why point 3 in section 1 matters: **eligibility comes entirely from
|
|
273
|
+
crew membership.** A shift cannot claim, declare, or negotiate a capability.
|
|
274
|
+
|
|
275
|
+
**Step 4 — the engine composes the posting.**
|
|
276
|
+
|
|
277
|
+
For the `builder` step, whose authored capability is `build`, and a run whose
|
|
278
|
+
modifier is `deep`:
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
composeCapabilities(['build'], 'deep') -> ['build:deep']
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
The order will be offered as `build:deep`.
|
|
285
|
+
|
|
286
|
+
**Step 5 — the hub decides how strictly to match.**
|
|
287
|
+
|
|
288
|
+
For each composed capability, the hub asks: *is any live crew certified for
|
|
289
|
+
this exact string?* "Live" means the `capability_routes` row exists **and** the
|
|
290
|
+
crew it names still exists — a row pointing at a deleted crew is dangling and
|
|
291
|
+
counts as nothing.
|
|
292
|
+
|
|
293
|
+
- `build:deep` has a live row (crew `openai`) → match mode **`exact`**. Only
|
|
294
|
+
crews certified for the exact string `build:deep` may claim.
|
|
295
|
+
- If it had no live row → see section 9.
|
|
296
|
+
|
|
297
|
+
**Step 6 — the match.**
|
|
298
|
+
|
|
299
|
+
`claimMatches(offered, caller, modes)`. Offered is `['build:deep']`. The
|
|
300
|
+
`openai-1` shift's caller set contains `build:deep`. Under `exact` mode
|
|
301
|
+
that is a match. The order is handed to `openai-1`, with
|
|
302
|
+
`order.capabilities = ['build:deep']`.
|
|
303
|
+
|
|
304
|
+
The `anthropic` shift, whose caller set is
|
|
305
|
+
`['wise', 'wise:deep', 'wise:express', 'wise:standard']`, does **not** match
|
|
306
|
+
— it is not certified for `build:deep`. That is the correct outcome, and it
|
|
307
|
+
is what stops a deep build job landing on the Anthropic shift. The two caller
|
|
308
|
+
sets do not overlap at all, which is exactly what it looks like when
|
|
309
|
+
eligibility comes entirely from crew membership and the crews are named after
|
|
310
|
+
teams.
|
|
311
|
+
|
|
312
|
+
**Step 7 — the shift picks the model.**
|
|
313
|
+
|
|
314
|
+
The `openai-1` shift reads `order.capabilities` — `['build:deep']` — and
|
|
315
|
+
looks it up in its merged crew roster:
|
|
316
|
+
|
|
317
|
+
1. Try the **exact compound**: `build:deep` → an ordered candidate array. Found.
|
|
318
|
+
2. If not found, try the **bare name part**: `build`.
|
|
319
|
+
3. If neither is found, the shift **refuses the order** with
|
|
320
|
+
`unresolvable-capability` and the hub re-offers it.
|
|
321
|
+
|
|
322
|
+
That third case is a real, deliberate refusal, not a crash. A shift that has no
|
|
323
|
+
rate for a job does not guess a model.
|
|
324
|
+
|
|
325
|
+
**Step 8 — the harness runs it.**
|
|
326
|
+
|
|
327
|
+
the selected roster candidate for the openai shifts, so the Codex CLI is spawned
|
|
328
|
+
with model `gpt-5.6-terra` and effort `xhigh`.
|
|
329
|
+
|
|
330
|
+
Valid efforts, in order: `low`, `medium`, `high`, `xhigh`, `max`.
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## 6. Why the model is chosen last, not first
|
|
335
|
+
|
|
336
|
+
A reasonable person asks: why not just write the model in the workflow
|
|
337
|
+
definition?
|
|
338
|
+
|
|
339
|
+
Because the definition is shared and the hardware is not. The same
|
|
340
|
+
`delivery.yaml` runs on a laptop with one API key, a CI box with another, and
|
|
341
|
+
someone else's fork entirely. A model name in the definition would be a promise
|
|
342
|
+
the author cannot keep.
|
|
343
|
+
|
|
344
|
+
So the definition says what *kind* of worker it needs. The hub says which
|
|
345
|
+
*teams* are certified. The machine owner says what those teams *run on*. Each
|
|
346
|
+
layer states only what it actually knows.
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## 7. Two shifts, one crew — and when that is wrong
|
|
351
|
+
|
|
352
|
+
The `openai` crew has exactly two staging shifts: `openai-1` and `openai-2`.
|
|
353
|
+
Both run codex and carry the same rate card. Because a crew is a team, both
|
|
354
|
+
become eligible for that crew's jobs.
|
|
355
|
+
|
|
356
|
+
**This works, with one consequence you must accept: which member gets the order
|
|
357
|
+
is a race.** First claim wins. The hub does not choose between eligible
|
|
358
|
+
members.
|
|
359
|
+
|
|
360
|
+
That is fine for a job where you genuinely do not care which member claims it
|
|
361
|
+
— a generic `coder` posting where either shift is acceptable.
|
|
362
|
+
|
|
363
|
+
For this staging pair, the two `openai` shifts must carry byte-identical rate
|
|
364
|
+
cards. Crew membership is what makes a shift eligible, and both members are
|
|
365
|
+
eligible for every capability the crew is certified for. If `openai-2` were
|
|
366
|
+
missing a row that `openai-1` has, the hub would eventually hand `openai-2` an
|
|
367
|
+
order it cannot price; `openai-2` would refuse with
|
|
368
|
+
`unresolvable-capability`; the hub would re-offer the order. That is the
|
|
369
|
+
claim-refuse-reoffer loop, and nothing about it is visible from the hub side —
|
|
370
|
+
the routing table is identical in both cases. This is why section 3c says both
|
|
371
|
+
openai cards are byte-identical.
|
|
372
|
+
|
|
373
|
+
This is a property of these two shifts sharing the `codex` adapter, not a
|
|
374
|
+
universal rule for every pair of shifts serving one crew. Shifts on different
|
|
375
|
+
adapters may use different model ids and separate settings directories; the
|
|
376
|
+
invariant is that every eligible shift must be able to resolve every capability
|
|
377
|
+
the crew is certified for.
|
|
378
|
+
|
|
379
|
+
It is exactly wrong for `wise:deep`, where the entire point is "this specific
|
|
380
|
+
one must be claude-fable-5." `wise:deep` is certified to `anthropic`, and
|
|
381
|
+
the anthropic card serves it with `claude-fable-5`, a different model from
|
|
382
|
+
every other `wise` row. If you want a guarantee about *which model*, you need
|
|
383
|
+
a crew whose members all run that model, and you certify that crew for the
|
|
384
|
+
compound.
|
|
385
|
+
|
|
386
|
+
One more failure mode: a step can declare a permission policy an adapter cannot
|
|
387
|
+
enforce (see `x.harness` in a step definition). A member on the wrong harness
|
|
388
|
+
releases the order with `incompatible-harness-policy`, and the hub re-offers it.
|
|
389
|
+
So a mixed crew can also produce a claim-then-release loop if the step's policy
|
|
390
|
+
is adapter-specific.
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## 8. Escalation — the per-step, temporary grade change
|
|
395
|
+
|
|
396
|
+
A step can declare an escalation:
|
|
397
|
+
|
|
398
|
+
```yaml
|
|
399
|
+
- name: builder
|
|
400
|
+
capabilities: [build]
|
|
401
|
+
escalation:
|
|
402
|
+
after: 3
|
|
403
|
+
modifier: deep
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
Read: *after this step's owed artifact has been judgment-rejected 3 times,
|
|
407
|
+
re-offer this step composed with `deep` instead of the run's own modifier.*
|
|
408
|
+
|
|
409
|
+
Four properties, all easy to get wrong:
|
|
410
|
+
|
|
411
|
+
1. **It is the engine's transition, not the worker's.** No agent reads this
|
|
412
|
+
block. A worker cannot opt in or out.
|
|
413
|
+
2. **It is per step and per run.** The `builder` escalating does not change
|
|
414
|
+
what `planner` or `reviewer` are offered as.
|
|
415
|
+
3. **It never rewrites the run's stored modifier.** The instance still says
|
|
416
|
+
`modifier = "standard"`. Only that one step's offer moved.
|
|
417
|
+
4. **It is a no-op on a run that is already at the target grade.** A `deep` run
|
|
418
|
+
whose builder escalates to `deep` just keeps re-offering `build:deep`.
|
|
419
|
+
|
|
420
|
+
The order carries a marker, `order.escalated = true`, so a reader can tell an
|
|
421
|
+
escalated re-offer from an ordinary one.
|
|
422
|
+
|
|
423
|
+
**A planner cannot upgrade the run's grade.** That feature does not exist. The
|
|
424
|
+
modifier is set at `start_run` and there is no code path that updates it. A
|
|
425
|
+
planner that thinks the human picked the wrong depth says so in its plan
|
|
426
|
+
document; it does not reroute itself.
|
|
427
|
+
|
|
428
|
+
---
|
|
429
|
+
|
|
430
|
+
## 9. When nobody is certified — the rule that is changing
|
|
431
|
+
|
|
432
|
+
This is the single line that has caused more confusion than everything else in
|
|
433
|
+
this document combined. It is worth reading twice.
|
|
434
|
+
|
|
435
|
+
**The situation:** a run is started with `--modifier express`. The `builder`
|
|
436
|
+
step composes to `build:express`. The hub looks in `capability_routes` and
|
|
437
|
+
finds **no live crew certified for `build:express`.**
|
|
438
|
+
|
|
439
|
+
### 9a. The OLD rule (what a current hub does)
|
|
440
|
+
|
|
441
|
+
The hub falls back to **name matching**: it offers the job to any crew
|
|
442
|
+
certified for anything whose name part is `build` — so the crew certified for
|
|
443
|
+
plain `build` claims it.
|
|
444
|
+
|
|
445
|
+
Why that is bad: the claiming shift receives `order.capabilities =
|
|
446
|
+
['build:express']`, finds no `build:express` row in its `roster`,
|
|
447
|
+
falls back to its bare `build` row, and runs on that model. The run believes it
|
|
448
|
+
got express service. It actually got whatever the generic build row happens to
|
|
449
|
+
be. Nothing failed, nothing was logged loudly, and the operator has no signal.
|
|
450
|
+
|
|
451
|
+
It converts the fact *"no shift is serving express right now"* into the
|
|
452
|
+
different fact *"the operator accepted a different grade of service."* Those
|
|
453
|
+
are not the same thing and the system had no business equating them.
|
|
454
|
+
|
|
455
|
+
### 9b. The NEW rule (what is being built)
|
|
456
|
+
|
|
457
|
+
**An unbound compound holds.** The hub keeps the mode at `exact`, so the order
|
|
458
|
+
simply waits until a crew certified for `build:express` clocks in. It does not
|
|
459
|
+
degrade to a generic worker.
|
|
460
|
+
|
|
461
|
+
**And the operator is told.** The hub writes a routing alert (kind
|
|
462
|
+
`binding-gap`) naming the capability that has no certified crew.
|
|
463
|
+
|
|
464
|
+
**Holding is not failure.** A held order is not dead. It is waiting. The
|
|
465
|
+
existing stall-notification system covers the case where a run sits too long,
|
|
466
|
+
and a crew that was restarted picks the work up when it comes back. There is no
|
|
467
|
+
built-in timer that silently downgrades the job.
|
|
468
|
+
|
|
469
|
+
The old behavior had a 15-minute escalation-fallback window baked in. That is
|
|
470
|
+
being removed. If an operator wants a timed fallback, they configure it; the
|
|
471
|
+
system does not assume it.
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
## 10. Reroute rules — saying "yes, substitute" on purpose
|
|
476
|
+
|
|
477
|
+
*(The engine half is in `owenloop`, the hub half is in `owenloop-service`, and
|
|
478
|
+
the CLI surface is `owenloop routing rule` — see
|
|
479
|
+
[Routing](cli.md#routing) in the CLI reference. The MCP surface follows.)*
|
|
480
|
+
|
|
481
|
+
Holding is the right default, but sometimes the operator genuinely does want a
|
|
482
|
+
substitution — "if nobody is serving `build:express` right now, `build:standard`
|
|
483
|
+
is fine." Section 9's rule makes that a decision the operator states, instead of
|
|
484
|
+
something the hub assumes.
|
|
485
|
+
|
|
486
|
+
A **reroute rule** is exactly that statement:
|
|
487
|
+
|
|
488
|
+
```
|
|
489
|
+
build:express -> build:standard
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
How it works, mechanically:
|
|
493
|
+
|
|
494
|
+
1. The hub composes the offer as usual and finds `build:express` has no live
|
|
495
|
+
binding.
|
|
496
|
+
2. The hub consults the operator's reroute rules and finds a target,
|
|
497
|
+
`build:standard`, that *does* have a live binding.
|
|
498
|
+
3. The hub hands the engine a **rewrite**: `{ 'build:express': 'build:standard' }`.
|
|
499
|
+
4. The engine **substitutes the string**. The order goes out as
|
|
500
|
+
`build:standard`, and carries `reroutedFrom: ['build:express']`.
|
|
501
|
+
5. The hub writes a routing alert (kind `reroute`) recording that it happened.
|
|
502
|
+
|
|
503
|
+
**Why substitute the string rather than just loosen the match?** Because the
|
|
504
|
+
claiming shift resolves its model from `order.capabilities`. If the hub merely
|
|
505
|
+
widened the match, the shift would receive `build:express`, find no row for it,
|
|
506
|
+
and fall back to its bare `build` row — the wrong model, which is the exact bug
|
|
507
|
+
section 9a describes. Substituting means the shift receives `build:standard` and
|
|
508
|
+
resolves *standard's* model, which is what the operator asked for.
|
|
509
|
+
|
|
510
|
+
**Why two fields on the order?** A rerouted order has two simultaneously true
|
|
511
|
+
answers to "which capability is this?"
|
|
512
|
+
|
|
513
|
+
- `capabilities` — the capability **being served**. This is what the shift
|
|
514
|
+
resolves its model against.
|
|
515
|
+
- `reroutedFrom` — the capability the definition **asked for**.
|
|
516
|
+
|
|
517
|
+
`reroutedFrom` is absent on every ordinary offer, so its presence alone tells a
|
|
518
|
+
reader the order is not running on what its definition requested. A single field
|
|
519
|
+
could only ever carry one of the two facts, and an operator asking "why did this
|
|
520
|
+
run on Opus?" would have no way back to "because we asked for express."
|
|
521
|
+
|
|
522
|
+
**The run's stored modifier is never touched by a reroute.** Re-reading the run
|
|
523
|
+
record still shows the grade of service that was requested. Only the offer
|
|
524
|
+
moved.
|
|
525
|
+
|
|
526
|
+
**Chains are resolved by the hub, not the engine.** If `a -> b` and `b -> c`,
|
|
527
|
+
the hub walks the chain and hands the engine the final answer. The engine
|
|
528
|
+
performs exactly one substitution and never looks a target up again, so a cycle
|
|
529
|
+
is impossible there rather than merely bounded.
|
|
530
|
+
|
|
531
|
+
### How an operator states and inspects all of this
|
|
532
|
+
|
|
533
|
+
The rules and the alerts are two separate command surfaces on one hub org — see
|
|
534
|
+
[Routing](cli.md#routing) in the CLI reference for flags, output shape and exit
|
|
535
|
+
codes.
|
|
536
|
+
|
|
537
|
+
| what you want | command |
|
|
538
|
+
|---|---|
|
|
539
|
+
| write the rule `build:express -> build:standard` | `owenloop routing rule add build:express build:standard` |
|
|
540
|
+
| put a rule ahead of the ones already there | `owenloop routing rule add build:express build --position 0` |
|
|
541
|
+
| see the rules in the order the hub tries them | `owenloop routing rule list` |
|
|
542
|
+
| take one rule back | `owenloop routing rule rm build:express build:standard` |
|
|
543
|
+
| see every hold, reroute, wait and fallback org-wide | `owenloop routing alerts` |
|
|
544
|
+
| see one run's routing timeline | `owenloop routing show <workflow>` |
|
|
545
|
+
|
|
546
|
+
**Three cautions the command names do not carry on their own.**
|
|
547
|
+
|
|
548
|
+
1. **A reroute rule is not a binding.** `routing rule add` writes a
|
|
549
|
+
`capability_reroutes` row, which names no crew and grants nobody access.
|
|
550
|
+
`capability bind` writes a `capability_routes` row, which does. A reroute
|
|
551
|
+
only reaches a crew if its **target** capability has a live binding of its
|
|
552
|
+
own, so adding a rule cannot by itself widen who may claim work.
|
|
553
|
+
2. **`routing rule list` order is meaning, not presentation.** Rows are grouped
|
|
554
|
+
by source capability and ordered by ascending `position` — the first row for
|
|
555
|
+
a capability is the first target the hub attempts.
|
|
556
|
+
3. **Removing the last rule for a capability restores holding.** With no rule
|
|
557
|
+
left, an unbound compound waits again, exactly as section 9b describes. The
|
|
558
|
+
CLI prints `remainingTargets: []` and says so on stderr.
|
|
559
|
+
|
|
560
|
+
---
|
|
561
|
+
|
|
562
|
+
## 11. The mistakes we keep making
|
|
563
|
+
|
|
564
|
+
Each of these has actually happened. Each has a one-line correction.
|
|
565
|
+
|
|
566
|
+
| Mistake | Correction |
|
|
567
|
+
|---|---|
|
|
568
|
+
| "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`. |
|
|
569
|
+
| "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. |
|
|
570
|
+
| "`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. |
|
|
571
|
+
| "A shift declares its capabilities." | It declares its **crew**. The hub derives capabilities from crew membership via `listCapabilitiesForCrews`. |
|
|
572
|
+
| "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. |
|
|
573
|
+
| "`--modifier` defaults to standard." | Omitting it means **no modifier**. Steps are offered on bare authored capabilities. |
|
|
574
|
+
| "A modifier means 'more effort'." | To the engine it is an opaque string. All meaning lives in the shift's `roster` map. |
|
|
575
|
+
| "A planner can decide the run needs to go deeper." | It can *say so*. It cannot change the run's modifier — no code path does. |
|
|
576
|
+
| "Escalation upgrades the run." | It re-offers **one step**, temporarily. The run's stored modifier is untouched. |
|
|
577
|
+
| "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). |
|
|
578
|
+
| "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. |
|
|
579
|
+
|
|
580
|
+
---
|
|
581
|
+
|
|
582
|
+
## 12. One-screen summary
|
|
583
|
+
|
|
584
|
+
```
|
|
585
|
+
delivery.yaml steps: [{ name: builder, capabilities: [build] }]
|
|
586
|
+
|
|
|
587
|
+
owenloop start --modifier deep (stored once, never changes)
|
|
588
|
+
|
|
|
589
|
+
engine composes build + deep -> "build:deep"
|
|
590
|
+
|
|
|
591
|
+
hub reads capability_routes: build:deep -> crew "openai"
|
|
592
|
+
|
|
|
593
|
+
hub derives caller set from the asking shift's crew memberships
|
|
594
|
+
|
|
|
595
|
+
match: exact -> only crews certified for "build:deep" may claim
|
|
596
|
+
|
|
|
597
|
+
the openai-1 shift claims; order.capabilities = ["build:deep"]
|
|
598
|
+
|
|
|
599
|
+
shift merges its crew roster:
|
|
600
|
+
"build:deep": [{ harness: codex, model: gpt-5.6-terra, effort: xhigh }]
|
|
601
|
+
|
|
|
602
|
+
the selected candidate spawns that model at that effort
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
If the lookup at step 3 finds nobody: the order **holds** and an alert is
|
|
606
|
+
written. If the operator has configured a reroute rule, the hub substitutes the
|
|
607
|
+
target capability and records `reroutedFrom` on the order.
|
package/docs/shift-logs.md
CHANGED
|
@@ -27,13 +27,29 @@ Do not collapse these — the rest of this page depends on telling them apart.
|
|
|
27
27
|
stderr are what `<run>.log` holds.
|
|
28
28
|
3. **The command a worker runs** — the `command:` text of a command step,
|
|
29
29
|
executed by the worker under `/bin/sh -c`. **Its** streams are captured into
|
|
30
|
-
the receipt the worker submits to the hub
|
|
30
|
+
the receipt the worker submits to the hub, and the worker relays the captured
|
|
31
|
+
tail (≤4 KiB) into its own output so a copy reaches `<run>.log`.
|
|
31
32
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
33
|
+
The worker never **inherits** the command's streams. Every relayed line carries
|
|
34
|
+
the literal ` | ` prefix. Both the receipt and `<run>.log` contain the
|
|
35
|
+
captured tail; full streams are represented only by the receipt's output hash
|
|
36
|
+
and stdout/stderr byte counts.
|
|
37
|
+
|
|
38
|
+
| Command outcome | Worker channel | Header |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| exit 0 and no machinery error | stdout | `… the command for step 'X' succeeded; its output follows` |
|
|
41
|
+
| anything else | stderr | `… the command for step 'X' exited N` / `was killed by …` / `could not be run (…)`; `its last output follows` |
|
|
42
|
+
|
|
43
|
+
Under shift dispatch fd 1 and fd 2 both point at the same file, so the header —
|
|
44
|
+
not the channel — is what tells these outcomes apart in `<run>.log`. The two
|
|
45
|
+
channels still matter: stderr is what a reader treats as trouble, and routine
|
|
46
|
+
success output there would make every green step look like a problem.
|
|
47
|
+
|
|
48
|
+
A command that printed nothing gets ` (the command produced no output)` on both
|
|
49
|
+
paths, because a gate that prints nothing is itself a diagnosis. The relay is
|
|
50
|
+
unconditional and has no off switch.
|
|
51
|
+
`packages/work/test/shift-logs-acceptance.test.ts` asserts that the marker
|
|
52
|
+
appears in `<run>.log` exactly once, as ` | <marker>`.
|
|
37
53
|
|
|
38
54
|
## Where the directory is
|
|
39
55
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "owenloop",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.8",
|
|
4
4
|
"description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "typicalday",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "owenloop",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.8",
|
|
4
4
|
"description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Typical Day"
|
|
@@ -66,8 +66,7 @@ x:
|
|
|
66
66
|
```
|
|
67
67
|
|
|
68
68
|
`id` is optional. When `id` is absent, the runtime may select the registered
|
|
69
|
-
default adapter; `--harness`
|
|
70
|
-
over the definition. Keep policy in `x.harness` even when `id` is absent.
|
|
69
|
+
default adapter; a selected crew-roster candidate takes precedence; `--harness` is a local debug override. Keep policy in `x.harness` even when `id` is absent.
|
|
71
70
|
|
|
72
71
|
When a producer declares native `judges:`, put `x.harness` on the producer
|
|
73
72
|
step, not on each judge entry. Every synthesized judge automatically inherits
|