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
|
@@ -1,23 +1,23 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* execution settings file writer — the ONE place the root `owenloop` CLI writes
|
|
3
|
+
* into the execution-side settings file.
|
|
4
4
|
*
|
|
5
|
-
* `
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
5
|
+
* `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
|
|
6
|
+
* settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
|
|
7
|
+
* NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
|
|
8
|
+
* `owenloop setup` can point `owenloop work` at the hub it just authenticated
|
|
9
|
+
* against.
|
|
10
10
|
*
|
|
11
11
|
* This module writes exactly ONE key — `hubOrigin` — and preserves every other
|
|
12
|
-
* key byte-for-byte (forward-compat with
|
|
13
|
-
* `stateDir`, `dispatchCap`, `commandRouting`, and any future
|
|
14
|
-
* never writes a secret: nothing secret is in scope here by
|
|
15
|
-
* hub ORIGIN is public).
|
|
12
|
+
* key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
|
|
13
|
+
* `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
|
|
14
|
+
* unknown key). It never writes a secret: nothing secret is in scope here by
|
|
15
|
+
* construction (the hub ORIGIN is public).
|
|
16
16
|
*
|
|
17
17
|
* Corrupt-file policy: a settings file that exists but does not parse as a JSON
|
|
18
18
|
* OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
|
|
19
|
-
* it cannot safely merge into. That mirrors
|
|
20
|
-
* family ("not an object").
|
|
19
|
+
* it cannot safely merge into. That mirrors the work settings validator's
|
|
20
|
+
* wording family ("not an object").
|
|
21
21
|
*
|
|
22
22
|
* Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
|
|
23
23
|
* util.ts — no CLI/engine closure.
|
|
@@ -27,21 +27,21 @@ import { dirname, join } from 'node:path';
|
|
|
27
27
|
import { writeFileAtomic } from "./hub.js";
|
|
28
28
|
import { CliError } from "./util.js";
|
|
29
29
|
/**
|
|
30
|
-
* The
|
|
31
|
-
* set and non-blank) wins over `HOME`, matching
|
|
30
|
+
* The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
|
|
31
|
+
* set and non-blank) wins over `HOME`, matching owenloop's own resolution and
|
|
32
32
|
* the owenloop credential store's `configDir`. Throws when neither is set.
|
|
33
33
|
*/
|
|
34
|
-
export function
|
|
34
|
+
export function owenloopSettingsPath(env) {
|
|
35
35
|
const xdg = env.XDG_CONFIG_HOME;
|
|
36
36
|
if (xdg && xdg.trim() !== '')
|
|
37
|
-
return join(xdg, '
|
|
37
|
+
return join(xdg, 'owenloop', 'settings.json');
|
|
38
38
|
const home = env.HOME;
|
|
39
39
|
if (home && home.trim() !== '')
|
|
40
|
-
return join(home, '.config', '
|
|
41
|
-
throw new CliError('cannot locate a config directory for
|
|
40
|
+
return join(home, '.config', 'owenloop', 'settings.json');
|
|
41
|
+
throw new CliError('cannot locate a config directory for execution settings: set HOME or XDG_CONFIG_HOME');
|
|
42
42
|
}
|
|
43
43
|
/**
|
|
44
|
-
* Read and parse the
|
|
44
|
+
* Read and parse the execution settings file at `path`.
|
|
45
45
|
*
|
|
46
46
|
* - Missing file → `null` (an absent settings file is not an error; the writer
|
|
47
47
|
* creates one).
|
|
@@ -50,7 +50,7 @@ export function owenworkSettingsPath(env) {
|
|
|
50
50
|
* `null`, a number, a string) → a hard `CliError` naming the path. The writer
|
|
51
51
|
* must never clobber a file it cannot merge into.
|
|
52
52
|
*/
|
|
53
|
-
export function
|
|
53
|
+
export function readOwenloopSettingsRaw(path) {
|
|
54
54
|
if (!existsSync(path))
|
|
55
55
|
return null;
|
|
56
56
|
let parsed;
|
|
@@ -58,24 +58,24 @@ export function readOwenworkSettingsRaw(path) {
|
|
|
58
58
|
parsed = JSON.parse(readFileSync(path, 'utf8'));
|
|
59
59
|
}
|
|
60
60
|
catch {
|
|
61
|
-
throw new CliError(`
|
|
61
|
+
throw new CliError(`execution settings file at ${path} is not valid JSON — fix or remove it before running setup`);
|
|
62
62
|
}
|
|
63
63
|
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
64
|
-
throw new CliError(`
|
|
64
|
+
throw new CliError(`execution settings file at ${path} is not a JSON object — fix or remove it before running setup`);
|
|
65
65
|
}
|
|
66
66
|
return parsed;
|
|
67
67
|
}
|
|
68
68
|
/**
|
|
69
|
-
* Set ONLY the `hubOrigin` key in the
|
|
69
|
+
* Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
|
|
70
70
|
* preserving every other key. Read the existing file (a parse failure is a hard
|
|
71
71
|
* `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
|
|
72
72
|
* directory, and write atomically (temp + rename via `writeFileAtomic`). The
|
|
73
73
|
* file is pretty-printed with a trailing newline. Returns the path and the
|
|
74
74
|
* previous `hubOrigin` (if any).
|
|
75
75
|
*/
|
|
76
|
-
export function
|
|
77
|
-
const path =
|
|
78
|
-
const existing =
|
|
76
|
+
export function writeOwenloopHubOrigin(env, origin) {
|
|
77
|
+
const path = owenloopSettingsPath(env);
|
|
78
|
+
const existing = readOwenloopSettingsRaw(path);
|
|
79
79
|
const previous = existing !== undefined && existing !== null && typeof existing.hubOrigin === 'string' ? existing.hubOrigin : undefined;
|
|
80
80
|
const merged = { ...(existing ?? {}), hubOrigin: origin };
|
|
81
81
|
mkdirSync(dirname(path), { recursive: true });
|
package/docs/authoring.md
CHANGED
|
@@ -78,12 +78,12 @@ steps:
|
|
|
78
78
|
# to the engine, passed through on the order
|
|
79
79
|
# (see below)
|
|
80
80
|
workdir: … # opaque hint passed through on the order; omitted when unset
|
|
81
|
-
|
|
82
|
-
command: … # required when
|
|
81
|
+
executor: agent # opaque executor value (default: agent); see below
|
|
82
|
+
command: … # required when executor: command; opaque, never shelled out
|
|
83
83
|
spec: # optional opaque config map, shape-checked like x: (a plain map)
|
|
84
84
|
anything: goes # contents never read by the engine; see below
|
|
85
|
-
|
|
86
|
-
# claim filtering (tick --
|
|
85
|
+
capabilities: [nightly, batch] # optional routing capabilities for peer-orchestrator
|
|
86
|
+
# claim filtering (tick --capability); empty = absent; see below
|
|
87
87
|
x: # optional; opaque extension map, passed through
|
|
88
88
|
anything: goes # untouched onto the order (Order.x); see design.md §27.3
|
|
89
89
|
```
|
|
@@ -91,7 +91,7 @@ steps:
|
|
|
91
91
|
## `model:` — quality tiers, not vendor ids
|
|
92
92
|
|
|
93
93
|
The engine never calls a model; `model:` is an opaque string that rides the
|
|
94
|
-
order to whatever dispatches your
|
|
94
|
+
order to whatever dispatches your Step Agents (an agent skill, a runner, your own
|
|
95
95
|
loop). Portable workflows should declare **intent** with one of four tier
|
|
96
96
|
names and let the dispatcher bind them to the host it runs on — Claude Code,
|
|
97
97
|
Codex, Gemini CLI, whatever:
|
|
@@ -112,87 +112,127 @@ a literal model id. Pin an exact model when you need reproducibility — just
|
|
|
112
112
|
know the def is now host-specific, on purpose. Omit `model:` entirely and the
|
|
113
113
|
dispatcher uses its default.
|
|
114
114
|
|
|
115
|
-
## `
|
|
115
|
+
## `executor:` — declaring the executor
|
|
116
116
|
|
|
117
117
|
Every step in every def written before this feature dispatches to an LLM
|
|
118
|
-
agent — that's still the default, and omitting `
|
|
119
|
-
def byte-for-byte unchanged. `
|
|
118
|
+
agent — that's still the default, and omitting `executor:` entirely leaves a
|
|
119
|
+
def byte-for-byte unchanged. `executor:` lets a step opt into a *different*
|
|
120
120
|
kind of executor instead: a shell command, a webhook, a browser-automation
|
|
121
121
|
runner, anything a dispatcher on the other end of `tick` knows how to run.
|
|
122
|
-
The engine never executes anything itself — `
|
|
122
|
+
The engine never executes anything itself — `executor:` is an opaque field
|
|
123
123
|
that rides the order (same pass-through contract as `model`) for whatever
|
|
124
|
-
drives your
|
|
124
|
+
drives your Step Agents to switch on.
|
|
125
125
|
|
|
126
126
|
```yaml
|
|
127
127
|
steps:
|
|
128
128
|
- name: tester
|
|
129
129
|
consumes: [reviewed_plan]
|
|
130
130
|
produces: [result]
|
|
131
|
-
|
|
132
|
-
command: npm test # required when
|
|
131
|
+
executor: command # opaque to the engine; default is 'agent'
|
|
132
|
+
command: npm test # required when executor: command; never parsed or shelled out
|
|
133
133
|
spec: # optional opaque config for the dispatcher
|
|
134
134
|
timeout: 300
|
|
135
135
|
workdir: .
|
|
136
|
-
body: "" # not required for
|
|
136
|
+
body: "" # not required for executor: command
|
|
137
137
|
```
|
|
138
138
|
|
|
139
139
|
Two shape rules, both enforced at load time, everything else opaque:
|
|
140
140
|
|
|
141
|
-
- **`
|
|
141
|
+
- **`executor: command` requires `command:`.** A `command`-executor step with no
|
|
142
142
|
`command:` is a load-time `DefError` — the dispatcher would have nothing to
|
|
143
143
|
run.
|
|
144
|
-
- **`
|
|
144
|
+
- **`executor: agent` (explicit) requires a real `body:`.** Omitting `executor:`
|
|
145
145
|
still defaults to `'agent'` and still needs no body-shape check beyond
|
|
146
146
|
today's behavior — this rule only fires when a step *explicitly* writes
|
|
147
|
-
`
|
|
147
|
+
`executor: agent` and leaves `body:` empty, which is almost certainly a
|
|
148
148
|
mistake (an agent step with no prompt).
|
|
149
149
|
|
|
150
|
-
Any other `
|
|
150
|
+
Any other `executor` value (`browser-automation`, `webhook`, your own executor value) is
|
|
151
151
|
fully opaque — no `body:`/`command:` requirement at all. A definition can
|
|
152
|
-
optionally declare `
|
|
152
|
+
optionally declare `executors: [agent, command]` at the top level as a typo
|
|
153
153
|
guard; when present, `validateDef` rejects any step (or judge — see below)
|
|
154
|
-
whose effective
|
|
154
|
+
whose effective executor (after the `agent` default) isn't in the list:
|
|
155
155
|
|
|
156
156
|
```yaml
|
|
157
157
|
name: my-workflow
|
|
158
|
-
|
|
158
|
+
executors: [agent, command] # optional allow-list; absent = any executor string accepted
|
|
159
159
|
```
|
|
160
160
|
|
|
161
161
|
`command:` and `spec:` are opaque the same way `x:` is: `command` is
|
|
162
162
|
shape-checked as a string, `spec` as a plain map, and neither is ever read or
|
|
163
|
-
interpreted by the engine beyond that. All three (`
|
|
163
|
+
interpreted by the engine beyond that. All three (`executor`, `command`,
|
|
164
164
|
`spec`) ride through `buildOrder` onto the emitted `Order` untouched, exactly
|
|
165
165
|
like `model` and `workdir`. See [`docs/design.md` §27.4](design.md) for the
|
|
166
166
|
full contract.
|
|
167
167
|
|
|
168
|
-
## `
|
|
169
|
-
|
|
170
|
-
`
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
168
|
+
## `capabilities:` — logical capability tags
|
|
169
|
+
|
|
170
|
+
`capabilities:` is an optional list of strings on a step naming what that step
|
|
171
|
+
*needs* — `gpu`, `repo-access` — not where it runs. They are part of **your**
|
|
172
|
+
vocabulary as a def author: a capability tag, chosen to describe the work.
|
|
173
|
+
An empty `capabilities:` list normalizes to absent.
|
|
174
|
+
|
|
175
|
+
**Never write a crew name in a def.** A crew is a deployment fact belonging to
|
|
176
|
+
one org on one hub; a def is portable. The indirection below is what keeps the
|
|
177
|
+
two apart.
|
|
178
|
+
|
|
179
|
+
**Golden path: most defs need no capabilities at all.** A step **without capabilities** routes
|
|
180
|
+
to the run's `defaultCrew` param if one was given, else to the starter's
|
|
181
|
+
personal crew. That is the default path, and it is the right one until you have
|
|
182
|
+
a fleet with genuinely different machines in it. Capabilities and routes are the
|
|
183
|
+
"advanced: teams & fleets" path — reach for a capability only when a step needs a
|
|
184
|
+
*specific* kind of machine.
|
|
185
|
+
|
|
186
|
+
### On a hub: an admin binds each capability to a crew
|
|
187
|
+
|
|
188
|
+
On a hub, every capability a step uses must be **bound to at least one crew by an org
|
|
189
|
+
admin** — `owenloop capability bind <capability> <crew>`, or Console → Settings → Capabilities.
|
|
190
|
+
A capability may bind several crews, and each `capability bind` ADDS one. See
|
|
191
|
+
[capability routes](cli.md#capability-routes) for the commands.
|
|
192
|
+
|
|
193
|
+
- **An unbound capability fails the run at `start_run`**, with an error naming the
|
|
194
|
+
capability and carrying the exact fix command. That fail-fast is deliberate: the
|
|
195
|
+
old behavior was an order that sat unserved forever. Route is **explicit
|
|
196
|
+
only** — there is no implicit fallback in which an unbound capability routes
|
|
197
|
+
somewhere by itself.
|
|
198
|
+
- **Routes are live, and that is the headline.** Adding a crew to a capability
|
|
199
|
+
widens who serves it at the next poll of every in-flight run; removing the
|
|
200
|
+
capability's **last live** route pauses the steps that use it until it is bound
|
|
201
|
+
again. As an author this means your def does **not** need re-publishing when
|
|
202
|
+
the fleet moves: the operator ADDS the new crew — from that moment both crews
|
|
203
|
+
serve the capability — and then REMOVES the old one, and your running work follows
|
|
204
|
+
across without a restart.
|
|
205
|
+
|
|
206
|
+
### Locally: capabilities are a tick filter
|
|
207
|
+
|
|
208
|
+
The local/OSS engine has no capability route table; there, the same capabilities act as a
|
|
209
|
+
work-splitting filter so several orchestrators ticking the *same* database can
|
|
210
|
+
divide the work. A tick caller may pass one or more `--capability <x>` filters (CLI)
|
|
211
|
+
or `engine.tick(wf, { capabilities: [...] })` (embedding), and a step is left for a
|
|
174
212
|
*different* caller only when **both** the caller's filter and the step's own
|
|
175
|
-
`
|
|
176
|
-
reason `
|
|
177
|
-
no filter at all) ticks it.
|
|
213
|
+
`capabilities:` are non-empty and share no value — that step's firings defer with
|
|
214
|
+
reason `capability-mismatch` until a caller whose filter matches (or a caller with
|
|
215
|
+
no filter at all) ticks it.
|
|
178
216
|
|
|
179
|
-
|
|
217
|
+
Capabilities are logical tags in both worlds; only the hub adds the route
|
|
218
|
+
indirection. Two consequences of the local filter are worth stating plainly:
|
|
180
219
|
|
|
181
220
|
- **Routing, not authorization.** A caller that passes *no* filter claims every
|
|
182
|
-
step,
|
|
183
|
-
without a filter.
|
|
184
|
-
boundary; never rely on them to keep a step away from a
|
|
221
|
+
step, with capabilities or not — and any Step Agent that can reach the database can tick
|
|
222
|
+
without a filter. Locally, capabilities are a work-splitting convenience, never a security
|
|
223
|
+
boundary; never rely on them to keep a step away from a Step Agent that shouldn't
|
|
185
224
|
run it.
|
|
186
|
-
- **Starvation hazard.** If every live caller ticks with a
|
|
187
|
-
none of them intersects a given step's
|
|
188
|
-
deferred forever with `
|
|
189
|
-
Operators running
|
|
225
|
+
- **Starvation hazard.** If every live caller ticks with a capability filter and
|
|
226
|
+
none of them intersects a given step's capabilities, that step's orders sit
|
|
227
|
+
deferred forever with `capability-mismatch` — no caller ever claims them.
|
|
228
|
+
Operators running capability-filtered callers should monitor the deferred/blocked entries
|
|
190
229
|
(each folded deferral in a `TickResult` carries its `reason`) so a
|
|
191
230
|
permanently unclaimed step is caught rather than silently stuck.
|
|
192
231
|
|
|
193
|
-
`
|
|
194
|
-
`
|
|
195
|
-
`
|
|
232
|
+
`capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
|
|
233
|
+
`executor:` says what *kind* of executor should run an order once it's claimed;
|
|
234
|
+
`capabilities:` says *which* caller may claim it in the first place — a tick filter
|
|
235
|
+
locally, a bound crew on a hub.
|
|
196
236
|
|
|
197
237
|
## `produces:` vs `generates:`
|
|
198
238
|
|
|
@@ -235,23 +275,23 @@ steps:
|
|
|
235
275
|
# reads the producer's inputs (question)
|
|
236
276
|
- name: ci-gate
|
|
237
277
|
body: "unused by a command judge, but still a required field" # every
|
|
238
|
-
# judge needs body/bodyFile regardless of
|
|
239
|
-
|
|
240
|
-
command: scripts/ci-gate.sh #
|
|
278
|
+
# judge needs body/bodyFile regardless of executor
|
|
279
|
+
executor: command # judges can be deterministic too — same
|
|
280
|
+
command: scripts/ci-gate.sh # executor:/command: contract as a normal step
|
|
241
281
|
maxAttempts: 5 # producer's cap (default for every produce on this step)
|
|
242
282
|
# — also bounds judge-reject → rebuild loops; `report`
|
|
243
283
|
# above could set its own maxAttempts: to override it
|
|
244
284
|
```
|
|
245
285
|
|
|
246
|
-
A judge entry accepts the same `
|
|
247
|
-
normal step (see [`
|
|
286
|
+
A judge entry accepts the same `executor:`/`command:`/`spec:` fields as a
|
|
287
|
+
normal step (see [`executor:` above](#executor--declaring-the-executor)) — a
|
|
248
288
|
judge can be a deterministic check (a script's exit status) instead of an
|
|
249
289
|
LLM verdict. Note `body:`/`bodyFile:` is still required on every judge
|
|
250
|
-
regardless of `
|
|
251
|
-
applies even to a `
|
|
290
|
+
regardless of `executor:` — that requirement is orthogonal to this feature and
|
|
291
|
+
applies even to a `executor: command` judge (the field just goes unread by a
|
|
252
292
|
non-agent dispatcher).
|
|
253
293
|
|
|
254
|
-
Each judge is a real step under the hood — it fires its own
|
|
294
|
+
Each judge is a real step under the hood — it fires its own Worker order
|
|
255
295
|
through the normal pipeline, with its own throttles (`cadence:`,
|
|
256
296
|
`maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
|
|
257
297
|
`report`, it lands `submitted` (not `green`) instead — schema-valid, but
|
|
@@ -365,7 +405,7 @@ for brand-new combined workflows where nothing downstream expects the original s
|
|
|
365
405
|
names.
|
|
366
406
|
|
|
367
407
|
**`calls:` (Mode 2, runtime)** delegates to a **separate child instance** at runtime
|
|
368
|
-
instead of inlining. The `calls:` step is machine-handled — it never emits a
|
|
408
|
+
instead of inlining. The `calls:` step is machine-handled — it never emits a Worker
|
|
369
409
|
job. Use it to embed an existing workflow as a black box, keeping its internals hidden.
|
|
370
410
|
|
|
371
411
|
```yaml
|
|
@@ -392,7 +432,7 @@ steps:
|
|
|
392
432
|
```
|
|
393
433
|
|
|
394
434
|
The engine spawns the child when the gate inputs are green, greens the parent's
|
|
395
|
-
`calls:` output when the child's declared output greens (no
|
|
435
|
+
`calls:` output when the child's declared output greens (no Worker run), and re-provides
|
|
396
436
|
inputs to the existing child if a gate input changes — it never spawns a duplicate.
|
|
397
437
|
|
|
398
438
|
| | `include:` (Mode 1) | `calls:` (Mode 2) |
|
|
@@ -429,7 +469,7 @@ By default a step fires when its consumed inputs are all green (`inputsGreen`).
|
|
|
429
469
|
evaluator*: a final step that inspects the finished workflow and greens an `outcome`.
|
|
430
470
|
- **`idle`** — fire when the workflow has made no progress for longer than `idleAfter`
|
|
431
471
|
(required). Use for a watchdog, a stuck-detector, or a timeout handler.
|
|
432
|
-
- **`[allGreen, idle]`** — both. The
|
|
472
|
+
- **`[allGreen, idle]`** — both. The Step Agent reads `order.cause` (`'allGreen'` or
|
|
433
473
|
`'idle'`) to branch.
|
|
434
474
|
|
|
435
475
|
```yaml
|
|
@@ -446,7 +486,7 @@ carry an empty input fingerprint, so a commit can never satisfy it, and
|
|
|
446
486
|
`owenloop lint` hard-errors on it. Declare the step's output under
|
|
447
487
|
`produces:`/`generates:` only.
|
|
448
488
|
|
|
449
|
-
**Alarms.** A
|
|
489
|
+
**Alarms.** A Step Agent that needs a heartbeat or a deadline can call
|
|
450
490
|
`engine.setAlarm(workflow, step, at)` with an absolute timestamp — it overrides the
|
|
451
491
|
relative `idleAfter` window and survives a process restart.
|
|
452
492
|
`engine.nextAlarm(workflow)` tells an external scheduler when to wake the instance.
|