owenloop 0.5.8 → 0.5.10
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 +69 -0
- package/README.md +81 -39
- package/bin/owenloop.mjs +16 -1
- package/dist/packages/work/src/agent/loop.d.ts +23 -8
- package/dist/packages/work/src/agent/loop.js +55 -6
- package/dist/packages/work/src/bundle/pull.d.ts +21 -0
- package/dist/packages/work/src/bundle/pull.js +118 -0
- package/dist/packages/work/src/consumed-verifier.js +6 -17
- package/dist/packages/work/src/exec/instructions.d.ts +4 -1
- package/dist/packages/work/src/exec/instructions.js +3 -0
- package/dist/packages/work/src/exec/loop.d.ts +2 -2
- package/dist/packages/work/src/exec/loop.js +273 -46
- 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/claude.js +116 -0
- package/dist/packages/work/src/harness/codex.d.ts +8 -0
- package/dist/packages/work/src/harness/codex.js +27 -1
- package/dist/packages/work/src/harness/contract.d.ts +9 -0
- 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 +84 -0
- package/dist/packages/work/src/main.js +1 -0
- package/dist/packages/work/src/roles/agent-run.js +57 -32
- package/dist/packages/work/src/roles/exec.js +27 -8
- package/dist/packages/work/src/roles/settings.js +2 -0
- 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 +84 -0
- package/dist/packages/work/src/settings/roster.js +364 -5
- 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 +14 -1
- package/dist/packages/work/src/settings/settings.js +14 -0
- package/dist/packages/work/src/shift/loop.d.ts +108 -5
- package/dist/packages/work/src/shift/loop.js +416 -54
- package/dist/packages/work/src/shift/protocol.d.ts +7 -5
- package/dist/packages/work/src/shift/runtime.d.ts +18 -0
- package/dist/packages/work/src/shift/runtime.js +104 -5
- package/dist/packages/work/src/shift/server.js +2 -0
- package/dist/packages/work/src/shift/spawn.d.ts +17 -2
- package/dist/packages/work/src/shift/spawn.js +16 -13
- 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/submit-proof.d.ts +11 -8
- package/dist/packages/work/src/submit-proof.js +11 -8
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +7 -1
- 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 +76 -6
- package/dist/src/capabilities.js +49 -6
- package/dist/src/capability-mapping-client.d.ts +29 -0
- package/dist/src/capability-mapping-client.js +160 -0
- package/dist/src/cli.d.ts +16 -3
- package/dist/src/cli.js +1925 -281
- package/dist/src/config-dir.d.ts +1 -1
- package/dist/src/config-dir.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 +2 -0
- package/dist/src/crypto/records.js +2 -0
- package/dist/src/defs.d.ts +38 -2
- package/dist/src/defs.js +593 -86
- package/dist/src/engine.d.ts +103 -25
- package/dist/src/engine.js +331 -79
- package/dist/src/hub.d.ts +77 -0
- package/dist/src/hub.js +162 -0
- package/dist/src/implements.d.ts +56 -0
- package/dist/src/implements.js +790 -0
- package/dist/src/index.d.ts +11 -9
- package/dist/src/index.js +6 -5
- package/dist/src/mcp/serve.d.ts +22 -0
- package/dist/src/mcp/serve.js +330 -41
- package/dist/src/mcp/server.d.ts +10 -7
- package/dist/src/mcp/server.js +53 -8
- package/dist/src/model.d.ts +48 -10
- package/dist/src/model.js +252 -99
- package/dist/src/order-resolver.d.ts +1 -0
- package/dist/src/order-resolver.js +8 -1
- package/dist/src/schemas/index.d.ts +11 -0
- package/dist/src/schemas/order.v1.schema.json +7 -1
- package/dist/src/store/def-source.d.ts +19 -0
- package/dist/src/store/def-source.js +87 -17
- package/dist/src/store/gc-recovery.d.ts +46 -0
- package/dist/src/store/gc-recovery.js +258 -0
- package/dist/src/store/gc.d.ts +94 -0
- package/dist/src/store/gc.js +562 -0
- package/dist/src/store/index.d.ts +3 -1
- package/dist/src/store/index.js +2 -0
- package/dist/src/store/install.d.ts +34 -5
- package/dist/src/store/install.js +73 -11
- package/dist/src/store/pre-commit-verifier.js +42 -2
- package/dist/src/store/snapshot-guard.d.ts +18 -0
- package/dist/src/store/snapshot-guard.js +94 -0
- package/dist/src/store.d.ts +69 -4
- package/dist/src/store.js +254 -16
- package/dist/src/types.d.ts +101 -20
- package/dist/src/util.js +4 -1
- package/docs/authoring.md +235 -10
- package/docs/bundles.md +45 -2
- package/docs/cli.md +437 -55
- package/docs/crypto.md +32 -10
- package/docs/design.md +177 -47
- package/docs/evals/mcp-charter-baseline.json +428 -0
- package/docs/mcp-charter-eval.md +124 -0
- package/docs/routing.md +189 -34
- package/docs/shift-logs.md +38 -9
- package/docs/wire-contracts.md +78 -14
- package/examples/workflows/compile-dev-playbook.yaml +1 -1
- package/examples/workflows/delivery.yaml +31 -14
- package/examples/workflows/ship.yaml +38 -4
- package/package.json +2 -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 +22 -0
- package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
- package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
- package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
- 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 +22 -0
- package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
- package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
- package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/docs/cli.md
CHANGED
|
@@ -4,9 +4,14 @@ The `owenloop` binary is a thin adapter over the engine: it maps `argv` to
|
|
|
4
4
|
engine calls and prints JSON to stdout. Everything here has a typed,
|
|
5
5
|
in-process equivalent — see [`docs/embedding.md`](embedding.md).
|
|
6
6
|
|
|
7
|
-
Global flags: `--db <path>` (env `OWENLOOP_DB`, default `.owenloop/state.db`)
|
|
8
|
-
`--defs <dir>` (env `OWENLOOP_DEFS`, default `./workflows`)
|
|
9
|
-
remembered between invocations — pass
|
|
7
|
+
Global flags: `--db <path>` (env `OWENLOOP_DB`, default `.owenloop/state.db`),
|
|
8
|
+
`--defs <dir>` (env `OWENLOOP_DEFS`, default `./workflows`), and `--verbose`.
|
|
9
|
+
Nothing is remembered between invocations — pass them on every command.
|
|
10
|
+
`--verbose` restores the detailed notice for every superseded bundle workflow;
|
|
11
|
+
without it, discovery emits at most one summary note such as
|
|
12
|
+
`note: 3 superseded bundle versions hidden; --verbose to list them`. The
|
|
13
|
+
actionable `has no selectable version` warning for competing non-SemVer bundle
|
|
14
|
+
versions remains unconditional. Opening the
|
|
10
15
|
**default** db path refuses a symlinked `.owenloop` directory — and a symlinked
|
|
11
16
|
`state.db` file (or any of its SQLite `-wal`/`-shm`/`-journal` sidecars) inside
|
|
12
17
|
a real `.owenloop` — rather than following it (filesystem-isolation guard
|
|
@@ -22,7 +27,7 @@ prints this usage and exits 0 without doing any work.
|
|
|
22
27
|
|
|
23
28
|
Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
|
|
24
29
|
`--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
|
|
25
|
-
`--strict-inputs`, `--unsigned`, and the bare `--now` on `reap`) never take a
|
|
30
|
+
`--strict-inputs`, `--unsigned`, `--verbose`, `--yes`, and the bare `--now` on `reap`) never take a
|
|
26
31
|
following value — the next token is always a positional or the next `--flag`,
|
|
27
32
|
never consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>`
|
|
28
33
|
on `tick`) for flags that do take a value.
|
|
@@ -38,6 +43,19 @@ both flags are passed, `--strict-inputs` wins. See
|
|
|
38
43
|
[`docs/design.md` §25](design.md#25-the-model-checker-owenloop-check--scope)
|
|
39
44
|
for the full breakdown.
|
|
40
45
|
|
|
46
|
+
Before `check` runs the model, it and `lint` validate cross-definition
|
|
47
|
+
`calls:` edges: a missing child, an undeclared mapped child input, a child with
|
|
48
|
+
zero or multiple outputs, and every member of a calls cycle are hard errors.
|
|
49
|
+
The lint JSON keeps those errors on the calling definition (and on every cycle
|
|
50
|
+
member); `check` presents them in its existing validation-error message.
|
|
51
|
+
|
|
52
|
+
Collection searches use `--max-collection N` to limit each `emit`/`seal` fork to
|
|
53
|
+
0 through N members (the default is 2). When the search actually expands a
|
|
54
|
+
reachable collection fork, text output prints a separate `COLLECTION CAP
|
|
55
|
+
APPLIED` caveat naming the flag and effective value. JSON output exposes the
|
|
56
|
+
same information as `collectionCapApplied` and `maxCollectionSize`; the marker
|
|
57
|
+
is independent of the `SEARCH INCOMPLETE` bounds notice.
|
|
58
|
+
|
|
41
59
|
## Commands
|
|
42
60
|
|
|
43
61
|
| command | what it does |
|
|
@@ -50,10 +68,13 @@ for the full breakdown.
|
|
|
50
68
|
| `bundle unpack <bundle.wnlp> <destination-dir>` | strictly validate and atomically extract a `.wnlp` package — see [Bundles](#bundles) |
|
|
51
69
|
| `bundle inspect <bundle.wnlp>` | strictly validate a `.wnlp` package and print its manifest and file metadata — see [Bundles](#bundles) |
|
|
52
70
|
| `bundle digest <bundle.wnlp>` | print the SHA-256 digest of the uncompressed canonical tar — see [Bundles](#bundles) |
|
|
71
|
+
| `bundle gc [--keep <n>] [--global] [--yes]` | dry-run or collect unreachable bundle-store objects — see [Bundles](#bundles) |
|
|
53
72
|
| `login [--hub <url>] [--with-token] [--as <slot>]` | authenticate the CLI against a hub — loopback OAuth, or `--with-token` from stdin — see [Hub](#hub-login--connect--push--logout) |
|
|
54
73
|
| `connect [--hub <url>] [--as <slot>]` | verify a resolved hub credential and record an optional per-project override in `.owenloop/hub.json` |
|
|
55
|
-
| `push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <url>] [--as <slot>]` | publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (idempotent against the hub's own def hashes) |
|
|
56
|
-
| `
|
|
74
|
+
| `push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--map <authored>=<org>] [--dry-run] [--hub <url>] [--as <slot>]` | publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (idempotent against the hub's own def hashes) |
|
|
75
|
+
| `install <owner>/<repo>[@ref] [<defName>...] [--map <authored>=<org>] [--accept-defaults] [--dry-run] [--hub <url>] [--as <slot>]` | publish an OUTSIDE repo's defs to your hub under SCOPED capabilities (`<defName>.<capability>` by default) — records the mapping BEFORE it publishes, and never writes into local `workflows/` — see below |
|
|
76
|
+
| `start <defName> [--provide name=json …] [--crew <name>] [--title <text>] [--modifier <name>] [--scope <label>] [--priority <low\|normal\|high>] [--hub <url>]` | start a published workflow on the bound hub with the human credential |
|
|
77
|
+
| `pending-gates --hub <url>` | list human-input gates currently blocking hub-hosted workflows; there is no local-engine form |
|
|
57
78
|
| `publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <url>]` | pack a canonical workflow bundle and publish a signed publication sidecar, with an optional signed origin sidecar, or an explicitly unsigned marker |
|
|
58
79
|
| `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
|
|
59
80
|
| `agent new <name> [--crews <a,b>] [--scopes <a,b>] [--shift] [--hub <url>]` | mint a new Scoped Identity on the hub and store its token in slot `agent:<name>` — the token is never printed; `--shift` = `--scopes work,run` — see [Hub](#hub-login--connect--push--logout) |
|
|
@@ -73,13 +94,20 @@ for the full breakdown.
|
|
|
73
94
|
| `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>] [--reuse-ssh-key <path>]` | onboard this machine: may store human and Scoped Identity credentials, ensure the three principal signing keys, relay the machine enrollment grant, write only execution-settings `hubOrigin`, and converge the bundled plugins for Claude Code and Codex — see [`setup`](#setup--onboard-a-machine) |
|
|
74
95
|
| `enrollments [--hub <url>]` | read and locally classify the hub's relayed machine enrollment grants; never creates keys or writes the roster — see [`enrollments`](#enrollments--inspect-machine-enrollment) |
|
|
75
96
|
| `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
|
|
76
|
-
| `roster show [crew]` | print the merged **crew roster
|
|
97
|
+
| `roster show [crew]` | print the offline merged **crew roster**, all inspected machine and cached-hub layers, winner provenance, cache age, and shadowed rows |
|
|
98
|
+
| `roster org [--hub <url>]` | read the live hub org-global and per-crew rosters (human credential) |
|
|
99
|
+
| `roster org put <capability> --candidate <harness>:<model>:<effort>… [--crew <name>] [--hub <url>]` | replace one org-global or named crew roster row (human admin credential) |
|
|
100
|
+
| `roster org rm <capability> [--crew <name>] [--hub <url>]` | remove one org-global or named crew roster row (human admin credential) |
|
|
101
|
+
| `roster registry [--hub <url>]` | read the hub's known harnesses, models, and efforts (human credential) |
|
|
102
|
+
| `roster registry put <harness> [--model <model>:<effort,effort…>]… [--display-name <text>] [--hub <url>]` | replace one harness's full hub model snapshot (human admin credential); omit every `--model` to clear it |
|
|
103
|
+
| `roster sync [--hub <url>] [--as agent\|agent:<account>]` | refresh the local hub-roster cache explicitly with the same agent credential a shift uses |
|
|
77
104
|
| `mcp [--hub <url>]` | serve the hub control plane to a local MCP host over stdio — spawned by MCP hosts, not run by humans — see [`mcp`](#mcp--stdio-control-plane-server-for-mcp-hosts) |
|
|
78
105
|
| `shift start <crew...>`, `shift next`, `shift status`, `shift end` | run the foreground shift daemon and its local clients — see [`shift`](#shift--foreground-daemon-and-client) |
|
|
79
106
|
| `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
|
|
107
|
+
| `util modifier-init --default <value>` | choose a modifier from rejection feedback, the order hint, or a default; intended for command steps |
|
|
80
108
|
| `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
|
|
81
109
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
82
|
-
| `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
|
|
110
|
+
| `provide <wf> <name> [--value json] [--hub <url>]` | supply a seeded input after the fact; `--hub` targets a hosted workflow |
|
|
83
111
|
| `tick <wf> [--now=<ms>] [--shallow] [--capability <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--capability` claims steps without capabilities plus matching-capability steps — see below |
|
|
84
112
|
| `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
|
|
85
113
|
| `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
|
|
@@ -90,18 +118,35 @@ for the full breakdown.
|
|
|
90
118
|
| `green <wf> <run> <path> [--value json] [--terminal]` | accept an owed output |
|
|
91
119
|
| `emit <wf> <run> --items '[{…},{…}]'` | add collection elements |
|
|
92
120
|
| `seal <wf> <run> [--value json]` | mark a collection complete |
|
|
93
|
-
| `reject <wf> <path> --by <author> --text <msg
|
|
121
|
+
| `reject <wf> <path> --by <author> --text <msg> [--requested <modifier>] [--hub <url>]` | reject an output (re-arms its producer); `--hub` targets a hosted workflow |
|
|
94
122
|
| `retract <wf> <path> --by <author> --text <msg>` | drop a collection member |
|
|
95
123
|
| `skip <wf> <path> --by <author> --text <msg>` | a step declines its own output |
|
|
96
|
-
| `retry <wf> <path> [--by a] [--text guidance]` | clear a stall
|
|
124
|
+
| `retry <wf> <path> [--by a] [--text guidance] [--hub <url>]` | clear a stall and reset the counter, or answer an `ask` — `--hub` targets a hub-hosted run |
|
|
97
125
|
| `close <wf> <run> [--outcome ok\|no_work\|failed\|skipped] [--summary s]` | release a claimed job |
|
|
98
126
|
| `delete <wf>` | delete an instance and all its rows |
|
|
99
127
|
| `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
|
|
100
128
|
|
|
129
|
+
Without `--hub`, `provide` and `reject` use the local SQLite engine exactly as
|
|
130
|
+
before. With `--hub`, they operate on the project-bound (or explicitly named)
|
|
131
|
+
hosted workflow and use the logged-in human credential; the explicit hub must
|
|
132
|
+
agree with an existing project binding. Hosted `reject` maps `--text` to the
|
|
133
|
+
hub's `reason`, forwards `--requested` when supplied, and does not accept
|
|
134
|
+
caller-controlled `--by` because the hub attributes the rejection to the
|
|
135
|
+
authenticated human. Hosted `provide` sends the input identifier as `name`.
|
|
136
|
+
|
|
137
|
+
Hosted workflow IDs must be `wf_` followed by exactly 24 lowercase hexadecimal
|
|
138
|
+
characters. The CLI rejects malformed IDs before resolving the hub, reading
|
|
139
|
+
credentials, or making a request for `cancel`, the `--hub` forms of `retry`,
|
|
140
|
+
`reject`, and `provide`, `instance show`, and `routing show`. Local
|
|
141
|
+
`provide`/`reject`/`retry` retain their SQLite behavior. Local `show` first
|
|
142
|
+
checks that the workflow instance exists: an existing instance with no
|
|
143
|
+
artifacts prints `[]`, while an unknown well-formed ID fails with
|
|
144
|
+
`no such workflow instance: <id>`.
|
|
145
|
+
|
|
101
146
|
## Bundles
|
|
102
147
|
|
|
103
|
-
|
|
104
|
-
store. `bundle pack`, `bundle inspect`, `bundle digest`, and `bundle unpack`
|
|
148
|
+
The package-format commands are deliberately dispatched before the CLI opens
|
|
149
|
+
the engine store. `bundle pack`, `bundle inspect`, `bundle digest`, and `bundle unpack`
|
|
105
150
|
read or write only the paths named by the command; they do not create
|
|
106
151
|
`.owenloop/state.db`, contact a remote coordinator, or use workflow definitions
|
|
107
152
|
from `--defs`. Successful commands print one JSON object on stdout. Failures
|
|
@@ -112,8 +157,60 @@ owenloop bundle pack <source-dir> [--output <bundle.wnlp>]
|
|
|
112
157
|
owenloop bundle unpack <bundle.wnlp> <destination-dir>
|
|
113
158
|
owenloop bundle inspect <bundle.wnlp>
|
|
114
159
|
owenloop bundle digest <bundle.wnlp>
|
|
160
|
+
owenloop bundle gc [--keep <n>] [--global] [--yes]
|
|
115
161
|
```
|
|
116
162
|
|
|
163
|
+
`bundle gc` is intentionally different from the four format commands: it reads
|
|
164
|
+
the selected content-addressed store plus the local runtime database's retained
|
|
165
|
+
definition snapshots. The project store under `--defs`/`OWENLOOP_DEFS` is the
|
|
166
|
+
default target; `--global` targets only `<home>/.owenloop/workflows` and cannot
|
|
167
|
+
be combined with a defs override. The other store may be read to establish
|
|
168
|
+
reachability. An applied run acquires both roots' writer locks in canonical
|
|
169
|
+
order, so installs cannot enter either side of the scan-to-delete window. Only
|
|
170
|
+
the selected root's bundle index and object tree are changed; coordinating with
|
|
171
|
+
a known but not-yet-created counterpart root may create its `.owenloop` lock
|
|
172
|
+
state so a concurrent first install uses the same lock. Project GC additionally
|
|
173
|
+
takes the legacy GitHub-add lock and recovers its separate journal before
|
|
174
|
+
clearing the staging tree those install routes share. Global GC takes that lock
|
|
175
|
+
as a read barrier while discovering project/add definition reachability, but
|
|
176
|
+
refuses a pending project journal rather than mutating the non-target project
|
|
177
|
+
tree. GC never contacts the hub.
|
|
178
|
+
|
|
179
|
+
GC is a pure dry run unless `--yes` is present. A dry run does not create a
|
|
180
|
+
missing store root, runtime database, lock, journal, or staging directory.
|
|
181
|
+
`--keep` is a positive integer and defaults to `2`: the selected/current version
|
|
182
|
+
plus one immediate rollback version, bounding history without eliminating the
|
|
183
|
+
cheapest fallback. The deterministic JSON report contains `ok`, `dryRun`,
|
|
184
|
+
`level`, `root`, `keep`, `count`, `bytes`, sorted `coordinates`, and sorted
|
|
185
|
+
`objects` with each digest's logical regular-file byte total and coordinates.
|
|
186
|
+
An unchanged `--yes` run reports the same candidates as its preceding dry run.
|
|
187
|
+
|
|
188
|
+
The collector protects every cross-root selected winner, the best `--keep`
|
|
189
|
+
versions of each qualified workflow, explicit index pins, every bundle digest
|
|
190
|
+
and lock dependency in retained local workflow snapshots, exact versioned
|
|
191
|
+
`calls:` edges in retained filesystem/add/legacy snapshots and currently
|
|
192
|
+
loadable non-CAS project/add definitions, and the exact coordinate+digest
|
|
193
|
+
dependency closure of every retained bundle in either index.
|
|
194
|
+
Project-to-global fallback is preserved. Protection is root-scoped: a complete
|
|
195
|
+
non-target coordinate/object copy can satisfy an exact edge without keeping a
|
|
196
|
+
redundant target copy, so `--keep` still bounds identical histories installed
|
|
197
|
+
in both roots. An all-non-SemVer candidate group is kept in full rather than
|
|
198
|
+
given an invented order. Multi-workflow bundles and multiple coordinates for
|
|
199
|
+
one digest are retained or collected atomically. Malformed indexes, objects,
|
|
200
|
+
links, special files, or snapshots fail closed before deletion.
|
|
201
|
+
|
|
202
|
+
Runtime snapshot writers share the relevant store writer locks and revalidate
|
|
203
|
+
CAS reachability before beginning SQLite. Store roots are guarded before lock
|
|
204
|
+
state is created, so a symlinked global parent cannot redirect coordination
|
|
205
|
+
writes. Bundle installs revalidate every
|
|
206
|
+
manifest lock against the combined store after taking their root lock and before
|
|
207
|
+
commit. GC therefore either observes a committed caller/pin, or a stale writer
|
|
208
|
+
is refused after collection and must reload. On filesystems that require a
|
|
209
|
+
temporary owner-write bit to move a hardened object, GC persists an
|
|
210
|
+
index-correlated journal first; all writers recover that journal before shared
|
|
211
|
+
staging cleanup, and the rename's source and destination parents are fsynced
|
|
212
|
+
before the evidence is cleared.
|
|
213
|
+
|
|
117
214
|
`pack` requires a source directory containing root `bundle.yaml` and every
|
|
118
215
|
workflow path listed by the manifest's `workflows` map. The source manifest is
|
|
119
216
|
not modified. If `--output` is omitted,
|
|
@@ -181,14 +278,14 @@ By default, the execution settings file is `$HOME/.owenloop/settings.json`.
|
|
|
181
278
|
For test or throwaway isolation, `OWENLOOP_CONFIG_DIR` may name an absolute
|
|
182
279
|
directory used verbatim; `XDG_CONFIG_HOME` is not consulted. In the paths below,
|
|
183
280
|
`<config>` means the resolved owenloop config directory. The same directory
|
|
184
|
-
holds `credentials.json`, `allowed_signers`, `org-root.pub`, `
|
|
281
|
+
holds `credentials.json`, `allowed_signers`, `org-root.pub`, `grants/`, and
|
|
185
282
|
`revocations/`.
|
|
186
283
|
|
|
187
284
|
### `shift start <crew...>`
|
|
188
285
|
|
|
189
286
|
```text
|
|
190
287
|
owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
|
|
191
|
-
[--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
|
|
288
|
+
[--cap <n>] [--max-agents <n>] [--exec-reserve <n>] [--local-queue-hold <ms>] [--poll-interval <ms>] [--once]
|
|
192
289
|
[--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
|
|
193
290
|
[--work-root <dir>]...
|
|
194
291
|
```
|
|
@@ -206,6 +303,8 @@ one loop sweep and exits instead of keeping the foreground daemon running.
|
|
|
206
303
|
| `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
|
|
207
304
|
| `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
|
|
208
305
|
| `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
|
|
306
|
+
| `--exec-reserve <n>` | slots inside `--cap` that `agent-run` children may never occupy, so an exec/command order always has room; precedence is flag, then `settings.execReserve`, then `1`. Clamped to `cap - 1`, so a `--cap 1` shift gets no reserve. `0` disables the reserve and lets agents fill the whole cap. This does not raise the total child ceiling — `--cap` still bounds every child. |
|
|
307
|
+
| `--local-queue-hold <ms>` | how long to retain a claim this shift cannot dispatch before returning it to the hub; precedence is flag, then `settings.localQueueHoldMs`, then `0`. The value is clamped to 90 seconds. `0` means the shift never holds an undispatchable claim locally, so another daemon can be offered it immediately. |
|
|
209
308
|
| `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
|
|
210
309
|
| `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
|
|
211
310
|
| `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
|
|
@@ -214,6 +313,16 @@ one loop sweep and exits instead of keeping the foreground daemon running.
|
|
|
214
313
|
| `--work-root <dir>` | **repeatable.** restrict this machine to orders whose working directory is inside one of these roots; precedence is the flags, then `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (a `:`-separated list), then `settings.allowedWorkdirRoots`. Each rung REPLACES the one below it rather than extending it. No rung set anywhere ⇒ **no restriction**, which is the default |
|
|
215
314
|
| `--log-max-age <ms>` | worker-log retention, swept once at startup; precedence is flag, then `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, then `settings.shiftLogMaxAgeMs`, then `1209600000` (14 days). `0` reaps every completed run's log at the next startup; there is no value that disables the sweep, and `shift.log` is never reaped |
|
|
216
315
|
|
|
316
|
+
**Capacity re-offer damping.** When a `dispatch-cap-full` or `agent-cap-full`
|
|
317
|
+
claim is returned immediately, the shift suppresses targeted `whats_next` for
|
|
318
|
+
that workflow and stable step (workflow, step, and fan-out key) for a fixed
|
|
319
|
+
30-second monotonic cooldown. A fresh hub run id does not bypass the cooldown.
|
|
320
|
+
The shift retries sooner when the relevant capacity returns: any total slot
|
|
321
|
+
for `dispatch-cap-full`, or room in the agent lane for `agent-cap-full`.
|
|
322
|
+
Untargeted inbox polling and sibling workflows continue, but command work in a
|
|
323
|
+
cooled workflow can wait until its cooldown expires. This shift-local damper
|
|
324
|
+
is separate from `--local-queue-hold` and from server `Retry-After` backoff.
|
|
325
|
+
|
|
217
326
|
**On-disk logs.** A running shift appends its dispatch record to
|
|
218
327
|
`<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
|
|
219
328
|
and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
|
|
@@ -254,25 +363,44 @@ directories an order is **allowed to name**. Neither derives from the other.
|
|
|
254
363
|
owenloop shift start build --work-root ~/code --work-root /srv/work
|
|
255
364
|
```
|
|
256
365
|
|
|
257
|
-
**Crew roster selection.**
|
|
258
|
-
roster** for capability routing, not the unrelated trust roster of signed
|
|
259
|
-
enrollment grants in `~/.owenloop/roster/`. A selected roster candidate decides
|
|
366
|
+
**Crew roster selection.** A selected roster candidate decides
|
|
260
367
|
the harness, model, and effort for an agent order. Its precedence is:
|
|
261
368
|
|
|
262
|
-
1. the first available candidate in the first matching crew roster
|
|
369
|
+
1. the first available candidate in the first matching crew roster named in
|
|
370
|
+
the hub-stamped `order.crews` sequence;
|
|
263
371
|
2. `owenloop work agent-run --harness` (a local debug override);
|
|
264
372
|
3. the verified step's `x.harness.id`;
|
|
265
373
|
4. the first registered adapter.
|
|
266
374
|
|
|
267
|
-
The shift
|
|
268
|
-
|
|
269
|
-
|
|
375
|
+
The shift advertises its start crews through worker → hub `serve_crews` and
|
|
376
|
+
its derived serving set through `serve_capabilities`. The latter is the raw
|
|
377
|
+
key union from the roster cascade (bare names and exact compounds are both
|
|
378
|
+
preserved), recomputed at startup and on the roughly 15-minute roster refresh;
|
|
379
|
+
it is not operator-set. **Today's hub ignores `serve_capabilities`; the
|
|
380
|
+
hub-side intersect ships separately.** The shift passes no crews to agent
|
|
381
|
+
workers. For a capability-bearing order, the worker resolves rosters only from
|
|
382
|
+
the hub-stamped `order.crews` list, in that stamped order. If the stamp is
|
|
383
|
+
missing, empty, malformed, or cannot be resolved locally, the worker refuses
|
|
384
|
+
and releases the order rather than falling back to the shift's start crews. The
|
|
385
|
+
complete strongest-first cascade for each stamped crew is: machine
|
|
386
|
+
`~/.owenloop/crews/<crew>.json`, machine
|
|
387
|
+
`~/.owenloop/settings.json` `roster`, the cached hub row for that crew, then
|
|
388
|
+
the cached hub org-global row. Hub rows live in a separate
|
|
389
|
+
`~/.owenloop/hub-rosters/` cache directory — never in the D5 trust
|
|
390
|
+
`~/.owenloop/grants/` directory. Each capability row is atomic:
|
|
270
391
|
the stronger layer replaces the weaker candidate array, and candidates are
|
|
271
392
|
tried in listed order. A step's `x.harness.id` is a policy constraint: a row
|
|
272
393
|
whose candidates do not include it is released as
|
|
273
394
|
`incompatible-harness-policy`; no available candidate is
|
|
274
395
|
`unresolvable-capability`.
|
|
275
396
|
|
|
397
|
+
The shift refreshes that hub cache at startup and periodically while parked;
|
|
398
|
+
`owenloop roster sync` is the manual repair path. Failed refreshes never stop a
|
|
399
|
+
shift or refuse an order: a missing or corrupt cache becomes an explicitly
|
|
400
|
+
reported absent layer and the machine rows keep routing. `owenloop roster show`
|
|
401
|
+
is offline by design, so it prints exactly the layers an `agent-run` child can
|
|
402
|
+
see, including fetch age and any lower-priority rows shadowed by a winner.
|
|
403
|
+
|
|
276
404
|
```json
|
|
277
405
|
{
|
|
278
406
|
"roster": {
|
|
@@ -305,6 +433,40 @@ file). `owenloop doctor` adds one line for each present crew roster file,
|
|
|
305
433
|
showing its found/absent layers and registered versus missing candidate
|
|
306
434
|
harnesses.
|
|
307
435
|
|
|
436
|
+
Crew names are data, not filesystem paths. A fresh safe crew keeps the literal
|
|
437
|
+
`~/.owenloop/crews/<crew>.json` filename for rollback compatibility. Unsafe or
|
|
438
|
+
too-wide names use the dedicated codec-only
|
|
439
|
+
`~/.owenloop/crews/.owenloop-machine-roster-codec-namespace-reserved-v1-ownership/`
|
|
440
|
+
directory: short names use a reversible `crew-hex--<lowercase-hex>.json` basename,
|
|
441
|
+
while names too wide for one filesystem component use a bounded
|
|
442
|
+
`crew-hex-hash--…` basename. The current codec's distinct `crew-hex--` prefix
|
|
443
|
+
and lowercase hexadecimal payload keep it disjoint from older base64url files
|
|
444
|
+
and stable on case-insensitive filesystems; explicitly owned older
|
|
445
|
+
`crew--<base64url>.json` files remain readable during migration. Every codec
|
|
446
|
+
file records its exact `crew` identity in
|
|
447
|
+
the JSON document, so a reversible basename alone can never claim an old
|
|
448
|
+
legacy file. Do not derive either filename by hand. The reserved directory
|
|
449
|
+
itself can be the prefix of a valid 64-character nested legacy crew name, so a
|
|
450
|
+
file inside it is codec storage only when its JSON `crew` identity reproduces
|
|
451
|
+
its codec basename; a shorter unowned child remains a legacy path. A complete
|
|
452
|
+
codec path is nevertheless too long to be a hub-valid legacy crew name.
|
|
453
|
+
Existing safe legacy
|
|
454
|
+
`<crew>.json` files — including names containing spaces, colons, percent
|
|
455
|
+
signs, Unicode, and (on POSIX) backslashes — plus any lexically contained
|
|
456
|
+
legacy tree such as `crews/foo/bar.json` for crew `foo/bar` — remain readable
|
|
457
|
+
and take precedence only when their on-disk spelling exactly matches the crew,
|
|
458
|
+
so `Delivery` and `delivery` cannot silently share one strongest layer on a
|
|
459
|
+
case-insensitive filesystem. The short-lived feature-branch directory
|
|
460
|
+
`.owenloop-encoded-rosters/` is treated as codec storage only when a file
|
|
461
|
+
declares the codec basename's exact `crew`; otherwise it remains a legacy
|
|
462
|
+
nested path. A literal crew name that spells an owned historical codec file is
|
|
463
|
+
distinct from that file's declared owner and receives its own current codec
|
|
464
|
+
path, never an alias of the historical strongest layer.
|
|
465
|
+
Routing probes only its requested crew paths. Doctor combines global file
|
|
466
|
+
diagnostics with the verified agent's crew list, so a malformed bounded hash
|
|
467
|
+
file is reported rather than silently disappearing. Traversal-shaped hub crew
|
|
468
|
+
names stay confined to the `crews/` directory.
|
|
469
|
+
|
|
308
470
|
A clean start or `--once` completion exits `0`. `owenloop shift --help` also
|
|
309
471
|
exits `0`. Runtime failures such as credential reads or socket/runtime setup
|
|
310
472
|
exit `1`. Usage and
|
|
@@ -326,6 +488,17 @@ version loops sharing the directory are configured with different total or
|
|
|
326
488
|
agent caps, each loop enforces its own configured limits under the shared lock.
|
|
327
489
|
Use identical cap settings for every loop sharing a state directory.
|
|
328
490
|
|
|
491
|
+
Reconciliation uses that same lock and re-checks record identity before it
|
|
492
|
+
changes anything: an abandoned reservation must still match the observed
|
|
493
|
+
reservation token, a dead child must still have the observed PID, and a
|
|
494
|
+
persisted start gate must still match both the observed PID and gate token. If
|
|
495
|
+
another loop re-dispatches the same run while a stale scan is waiting for the
|
|
496
|
+
lock, the replacement record and gate are preserved and no `abandoned` or
|
|
497
|
+
`reaped` event is reported. Startup reconciliation defers briefly when the
|
|
498
|
+
lock is busy and the poll loop retries it. A worker exit notification releases
|
|
499
|
+
its PID record on every terminal outcome, including a clean exit with status
|
|
500
|
+
`0`; reconciliation remains the crash/restart backstop.
|
|
501
|
+
|
|
329
502
|
Canonical `*.json` child and reservation records are capacity-bearing state.
|
|
330
503
|
Missing records are benign, including a record that disappears between listing
|
|
331
504
|
and read. A truncated, malformed, or unreadable canonical record is not benign:
|
|
@@ -384,7 +557,7 @@ either `exec` or `agent-run`:
|
|
|
384
557
|
- `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
|
|
385
558
|
- `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
|
|
386
559
|
- `bundle-miss`: `{ "type": "bundle-miss", "workflow": "...", "def": "..." }` — a legacy order named a def with no cached bundle, so it was left for hub pickup
|
|
387
|
-
- `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`); display `message`
|
|
560
|
+
- `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`, `agent-lane-closed`, `dispatch-cap-full`, `agent-cap-full`, `claim-expired`); display `message`. The capacity, expiry, and `agent-lane-closed` reasons return the claim to the hub; malformed and unsupported reasons leave it for the pickup window.
|
|
388
561
|
- `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
|
|
389
562
|
|
|
390
563
|
Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
|
|
@@ -429,11 +602,13 @@ owenloop shift status [--state-dir <p>]
|
|
|
429
602
|
With a daemon, status exits `0` and prints:
|
|
430
603
|
|
|
431
604
|
```json
|
|
432
|
-
{ "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
|
|
605
|
+
{ "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "agent_ceiling": 2, "attended_at": null, "started_at": 1738000000000 }
|
|
433
606
|
```
|
|
434
607
|
|
|
435
|
-
`
|
|
436
|
-
|
|
608
|
+
`agent_ceiling` is the effective maximum number of `agent-run` children after
|
|
609
|
+
applying `--max-agents`, `--cap`, and `--exec-reserve`; command and exec work
|
|
610
|
+
may still use any free slot inside `cap`. `attended_at` remains `null` until the
|
|
611
|
+
first accepted `next` request. Without a daemon, status is still a successful question: it exits `0` and prints
|
|
437
612
|
`{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
|
|
438
613
|
other client/runtime errors exit `1`.
|
|
439
614
|
|
|
@@ -482,6 +657,28 @@ The execution settings file is `<config>/settings.json` (see
|
|
|
482
657
|
| `release --session <id> [options]` | drain a session's held claims |
|
|
483
658
|
| `settings` | print the resolved execution settings file |
|
|
484
659
|
| `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
|
|
660
|
+
| `util modifier-init --default <value>` | print the requested modifier from `OWENLOOP_FEEDBACK`, else `OWENLOOP_MODIFIER`, else the required default |
|
|
661
|
+
|
|
662
|
+
### `util modifier-init`
|
|
663
|
+
|
|
664
|
+
`owenloop util modifier-init --default <value>` is a deterministic helper for
|
|
665
|
+
a command step that produces a bound modifier artifact. It prints one value and
|
|
666
|
+
does no model or harness work. Its precedence is:
|
|
667
|
+
|
|
668
|
+
1. the newest `reject` reason carrying `requested` in `OWENLOOP_FEEDBACK`;
|
|
669
|
+
2. the current order modifier in `OWENLOOP_MODIFIER`;
|
|
670
|
+
3. the required `--default` value.
|
|
671
|
+
|
|
672
|
+
The helper accepts a single-word result only. It reads feedback inline from
|
|
673
|
+
`OWENLOOP_FEEDBACK` or from the temporary path in `OWENLOOP_FEEDBACK_FILE`,
|
|
674
|
+
using the same 64 KiB threshold and collision rule as consumed inputs. Exit 0
|
|
675
|
+
prints the value; exit 2 is a usage error; exit 3 means the feedback could not
|
|
676
|
+
be parsed or the resolved value was invalid.
|
|
677
|
+
|
|
678
|
+
The helper prints the selected word as ordinary stdout. A command artifact is
|
|
679
|
+
submitted as the full `CommandReceipt`; if a workflow binds a field inside a
|
|
680
|
+
command payload, the command must emit the `##owenloop:payload##` JSON marker and
|
|
681
|
+
the bind must name that field (for example, `from: payload.value`).
|
|
485
682
|
|
|
486
683
|
### `work agent-run` — the only Step Agent dispatcher
|
|
487
684
|
|
|
@@ -568,11 +765,11 @@ separate concern.
|
|
|
568
765
|
`owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
|
|
569
766
|
`workflows/**` folder (via GitHub's REST API and Node's built-in `fetch` — no
|
|
570
767
|
new dependency), validates every def with the same lint/validate/`check`
|
|
571
|
-
machinery `owenloop lint`/`owenloop check` use
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
under `<defsDir>/<owner>-<repo>-<hash>/`, where `<hash>` is the first 8 hex
|
|
768
|
+
machinery `owenloop lint`/`owenloop check` use. Those authoring commands now
|
|
769
|
+
also report invalid cross-definition `calls:` edges. `add` retains a strict
|
|
770
|
+
whole-staged-tree backstop for include expansion and final load validation, so
|
|
771
|
+
any remaining tolerant raw-loader failure still refuses the install — and only
|
|
772
|
+
then installs them under `<defsDir>/<owner>-<repo>-<hash>/`, where `<hash>` is the first 8 hex
|
|
576
773
|
characters of `sha256(owner/repo)`. The hash keeps distinct sources that used
|
|
577
774
|
to collide on the same `<owner>-<repo>` folder (e.g. `a-b/c` and `a/b-c`)
|
|
578
775
|
from clobbering each other. `owner` and `repo` are restricted to the
|
|
@@ -716,16 +913,25 @@ defs dir is guarded only on the default `cwd/workflows` fallback — an explicit
|
|
|
716
913
|
matching the `--db`/`OWENLOOP_DB` rule above.
|
|
717
914
|
|
|
718
915
|
**Installed-def discovery.** Defs installed by `add` are discovered by default:
|
|
719
|
-
a plain `owenloop defs`/`create`/`tick` against the DEFAULT defs dir
|
|
916
|
+
a plain `owenloop defs`/`lint`/`check`/`create`/`tick` against the DEFAULT defs dir
|
|
720
917
|
(`cwd/workflows`) sees them by name, no `--defs` flag needed. `loadDefs` itself
|
|
721
918
|
stays a pure dir-scanner (top-level `*.yaml` plus immediate-subdir
|
|
722
919
|
`workflow.yaml`); the CLI folds installed subfolders in on top, ledger-driven and
|
|
723
920
|
bounded — it only loads folders named by the fail-closed-validated
|
|
724
921
|
`.owenloop/installed.json` entries, never a raw recurse of the tree.
|
|
725
922
|
|
|
923
|
+
**Definition listing.** The default JSON from `owenloop defs` retains each
|
|
924
|
+
definition's `name`, nullable `title`, ordered input-name `inputs`, and ordered
|
|
925
|
+
`steps`. It additively includes ordered `inputSchemas` entries (always `name`,
|
|
926
|
+
with complete `schema` when declared) and a present-only opaque `x` extension
|
|
927
|
+
bag. Schemas and extension bags are returned in full, never truncated; the
|
|
928
|
+
larger default terminal payload is the intentional tradeoff for making this the
|
|
929
|
+
discovery surface without requiring prior knowledge of a flag.
|
|
930
|
+
|
|
726
931
|
- **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
|
|
727
932
|
operator intent to target a literal dir and keeps the pure-scan behavior with
|
|
728
|
-
no installed-def or CAS-store fold-in
|
|
933
|
+
no installed-def or CAS-store fold-in for `defs`, `lint`, `check`, and runtime
|
|
934
|
+
commands — the rule is "was an override given",
|
|
729
935
|
so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
|
|
730
936
|
Pointing `--defs` straight at an install folder
|
|
731
937
|
(`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
|
|
@@ -736,9 +942,12 @@ bounded — it only loads folders named by the fail-closed-validated
|
|
|
736
942
|
- **Fail-open.** The fold-in never breaks base loading. A corrupt or
|
|
737
943
|
structurally-invalid `installed.json`, a missing install folder, or an install
|
|
738
944
|
folder that fails to load each emits a `warning:` on stderr and is skipped;
|
|
739
|
-
your project defs still load and
|
|
740
|
-
|
|
741
|
-
|
|
945
|
+
your project defs still load and commands still exit 0, except that directory
|
|
946
|
+
`lint` exits 1 when it reports a failed installed-folder load. A malformed or
|
|
947
|
+
duplicate definition skips its entire installed folder for both authoring and
|
|
948
|
+
executable discovery; directory `lint` also reports that folder as a failed
|
|
949
|
+
load. The add-time fail-closed lockfile validation is unchanged — discovery
|
|
950
|
+
consumes it and simply refuses to act on a bad ledger rather than crashing.
|
|
742
951
|
|
|
743
952
|
Public repos only — no auth/token support yet; a private repo (or a bad
|
|
744
953
|
ref) surfaces as a 404 from the sha-resolve step.
|
|
@@ -1340,6 +1549,17 @@ usage errors before credential or network access. The command does not claim,
|
|
|
1340
1549
|
dispatch, close, or otherwise drive work—the standing Shift discovers the run
|
|
1341
1550
|
through its normal crew inbox.
|
|
1342
1551
|
|
|
1552
|
+
`--scope <label>` is forwarded as the run's `scope`: a free routing label
|
|
1553
|
+
recorded on the instance, with no registry and no fixed set of values. Omit it
|
|
1554
|
+
and the run carries no scope. `--priority <low|normal|high>` is forwarded as the
|
|
1555
|
+
run's `priority`; omit it and the hub applies `normal`. A value outside
|
|
1556
|
+
`low|normal|high` is a local usage error before any credential or network
|
|
1557
|
+
access, not a forwarded request. Like `--crew`/`--title`, a bare
|
|
1558
|
+
`--scope`/`--priority` or a `--scope=`/`--priority=` is a local usage error.
|
|
1559
|
+
Both are recorded at start only and are never writable afterwards. Do not
|
|
1560
|
+
confuse `--scope` (this routing label) with `--scopes` on `agent new`/`setup`,
|
|
1561
|
+
which lists an agent token's authorization scopes.
|
|
1562
|
+
|
|
1343
1563
|
### `cancel` — stop a running instance
|
|
1344
1564
|
|
|
1345
1565
|
`owenloop cancel <workflow>` sends `POST /api/cancel_run` and prints whether the
|
|
@@ -1457,6 +1677,14 @@ stream cancelled) rather than buffered, closing the same memory-exhaustion gap
|
|
|
1457
1677
|
on the hub path that the `add` download cap closes on the archive path.
|
|
1458
1678
|
`OWENLOOP_HUB_MAX_RESPONSE_BYTES` overrides the cap (a test knob).
|
|
1459
1679
|
|
|
1680
|
+
**Authentication failures.** On the credential-verification and shared
|
|
1681
|
+
authenticated-read paths, a `401` keeps its credential-specific message, while
|
|
1682
|
+
a `429` is reported as `rate limited by the hub`. When the hub sends a
|
|
1683
|
+
`Retry-After` header, the CLI appends ` (retry after VALUE)`; it does not parse
|
|
1684
|
+
the value or sleep automatically. Other non-2xx responses keep the generic
|
|
1685
|
+
status-bearing hub-rejected message. Login verifies before storing, so a failed
|
|
1686
|
+
verification — including a `429` — never writes the credential.
|
|
1687
|
+
|
|
1460
1688
|
### `login` — authenticate the CLI against a hub
|
|
1461
1689
|
|
|
1462
1690
|
Two ways to get a credential, both of which **verify before storing** (a token
|
|
@@ -1734,6 +1962,18 @@ On a `401`, an OAuth credential is refreshed once and the request retried; an
|
|
|
1734
1962
|
agent (`olp_`) token has no refresh path, so a `401` is a hard "re-mint it"
|
|
1735
1963
|
error.
|
|
1736
1964
|
|
|
1965
|
+
**`--map <authored>=<org>`** (repeatable) records a capability mapping for the
|
|
1966
|
+
defs being pushed, before any of them is published. It is the same mechanism
|
|
1967
|
+
[`install`](#install--publish-an-outside-repos-defs-under-scoped-capabilities)
|
|
1968
|
+
uses, exposed here for the case where an org-authored def's capability should
|
|
1969
|
+
resolve to a different org name — `push` itself scopes nothing, because a def
|
|
1970
|
+
you authored is already in your org's vocabulary. Only the non-identity entries
|
|
1971
|
+
a given def actually authors are written for it; a `--map` naming a capability
|
|
1972
|
+
no selected def authors is an error. Because the write precedes the publish, a
|
|
1973
|
+
hub with no mapping writer fails the push with nothing sent (exit 2), and no
|
|
1974
|
+
shipped hub implements that write yet — so `--map` is currently a
|
|
1975
|
+
fail-closed declaration of intent.
|
|
1976
|
+
|
|
1737
1977
|
**Include and bodyFile limitations.** A def whose file uses `include:` is
|
|
1738
1978
|
refused (`uses include:, not hub-pushable`): the hub's `create_workflow`
|
|
1739
1979
|
parses the raw YAML without include expansion, and a re-serialized expanded
|
|
@@ -1742,6 +1982,73 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
|
|
|
1742
1982
|
resolve the external file against once the YAML leaves this machine. Inline
|
|
1743
1983
|
both before pushing.
|
|
1744
1984
|
|
|
1985
|
+
### `install` — publish an outside repo's defs under scoped capabilities
|
|
1986
|
+
|
|
1987
|
+
```text
|
|
1988
|
+
owenloop install <owner>/<repo>[@ref] [<defName>...] [--map <authored>=<org>] [--accept-defaults] [--dry-run] [--hub <origin>] [--as <slot>]
|
|
1989
|
+
```
|
|
1990
|
+
|
|
1991
|
+
`install` is a **sibling of [`push`](#push--publish-local-defs-to-the-resolved-hub), not of [`add`](#add--installing-shared-workflow-defs-from-github)**. It
|
|
1992
|
+
publishes to your hub. It never writes into the local `workflows/` directory —
|
|
1993
|
+
`add` owns local installation, with its install lock, crash journal and atomic
|
|
1994
|
+
swap, and duplicating that here would be a second implementation of the same
|
|
1995
|
+
transaction. The outside repo is materialized into a temp directory, used, and
|
|
1996
|
+
deleted.
|
|
1997
|
+
|
|
1998
|
+
**Sources.** Only `owner/repo[@ref]` (a public GitHub repo) is an install source
|
|
1999
|
+
today. A local `.wnlp` bundle or an `http(s)` URL is refused, naming the two
|
|
2000
|
+
commands that do cover it: `owenloop add <source>` to install into the local
|
|
2001
|
+
store, then `owenloop push --bundle <bundle.wnlp>` to publish it.
|
|
2002
|
+
|
|
2003
|
+
**Capabilities are scoped by default.** `push` publishes defs you authored, so
|
|
2004
|
+
their capabilities join your org's shared vocabulary as written. A def from an
|
|
2005
|
+
unrelated author making the same claim is not the same claim, so every
|
|
2006
|
+
capability an installed def authors becomes `<defName>.<capability>` —
|
|
2007
|
+
`analyzer.review`, not `review`. A def name can never contain a dot and the def
|
|
2008
|
+
parser reserves only `:`, so the dot splits the two halves unambiguously and
|
|
2009
|
+
needs no new separator or escaping. The def's content is never edited: the
|
|
2010
|
+
mapping is org-side data recorded against `(def, authored-name)` on the hub, so
|
|
2011
|
+
upstream updates keep applying.
|
|
2012
|
+
|
|
2013
|
+
**Deciding the vocabulary,** highest precedence first: `--map <authored>=<org>`
|
|
2014
|
+
(repeatable); a mapping this hub already holds for that def, carried forward
|
|
2015
|
+
unchanged; `--accept-defaults`, which takes the scoped name for everything;
|
|
2016
|
+
otherwise one prompt per capability, prefilled with the scoped name, printed
|
|
2017
|
+
after the org's live vocabulary so a decision to link is an informed one. A
|
|
2018
|
+
`--map` naming a capability no selected def authors is an error, never a silent
|
|
2019
|
+
no-op. A mapping target containing `:` is refused — that suffix position is
|
|
2020
|
+
reserved for the run modifier the engine composes at offer time.
|
|
2021
|
+
|
|
2022
|
+
**The non-interactive guard fires before the first hub request.** A piped run
|
|
2023
|
+
with neither `--map` nor `--accept-defaults` exits 1 naming both flags, with an
|
|
2024
|
+
empty request log — never after a mapping read has already happened.
|
|
2025
|
+
|
|
2026
|
+
**Record, then publish, and that ordering is the point.** Publishing first would
|
|
2027
|
+
put an unscoped third-party def into your org's vocabulary for the window
|
|
2028
|
+
between the two calls — exactly the trust-boundary breach this verb exists to
|
|
2029
|
+
prevent. A hub that cannot record the mapping therefore fails the command with
|
|
2030
|
+
**nothing published**. Identity entries are skipped (the hub's resolver drops
|
|
2031
|
+
them anyway), as are entries the hub already holds.
|
|
2032
|
+
|
|
2033
|
+
**No shipped hub implements the mapping write yet.** Until one does, only the
|
|
2034
|
+
identity case completes end to end — where every capability keeps its authored
|
|
2035
|
+
name there is nothing to record, so the write is skipped and the publish
|
|
2036
|
+
proceeds. Every other case stops at the missing verb with exit 2, before any
|
|
2037
|
+
`create_workflow` call.
|
|
2038
|
+
|
|
2039
|
+
Everything downstream of the mapping is `push`'s machinery, unchanged: the same
|
|
2040
|
+
all-or-nothing lint/validate/`check` gate across every selected def, the same
|
|
2041
|
+
`GET /api/workflows` server diff, the same topological `calls:` ordering with
|
|
2042
|
+
dependency skips, the same `401` refresh-once and `429` batch halt. `--dry-run`
|
|
2043
|
+
reports `mapped` and `wouldRecord` alongside the usual plan and writes nothing.
|
|
2044
|
+
stdout is machine-parseable JSON; the mapping decisions, the diff, and the hub's
|
|
2045
|
+
capability report go to stderr.
|
|
2046
|
+
|
|
2047
|
+
Exit codes: 0 ok; 1 a runtime or hub error (a validation-gate refusal, a per-def
|
|
2048
|
+
rejection, a refused source kind, an invalid `--map`, or a credential the hub
|
|
2049
|
+
rejects after its one refresh — as in `push`); 2 the hub is unresolvable or does
|
|
2050
|
+
not implement the mapping write; 3 no credential is stored for the slot.
|
|
2051
|
+
|
|
1745
2052
|
### `publish` — pack and publish a workflow bundle
|
|
1746
2053
|
|
|
1747
2054
|
```text
|
|
@@ -2402,7 +2709,7 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
|
|
|
2402
2709
|
|
|
2403
2710
|
## `setup` — onboard a machine
|
|
2404
2711
|
|
|
2405
|
-
`owenloop setup` is the one-shot onboarding command. It runs
|
|
2712
|
+
`owenloop setup` is the one-shot onboarding command. It runs eight ordered steps.
|
|
2406
2713
|
Depending on the machine state, setup may store the human credential, mint or
|
|
2407
2714
|
rekey and store a Scoped Identity credential, ensure the three principal
|
|
2408
2715
|
signing keys, relay a signed machine enrollment grant, and write only
|
|
@@ -2429,7 +2736,15 @@ plugin version already installed performs no plugin writes. The steps:
|
|
|
2429
2736
|
5. **execution settings** — write only `hubOrigin` into the execution settings
|
|
2430
2737
|
file so the local Step Agent talks to this hub, preserving every other key
|
|
2431
2738
|
(skipped when `hubOrigin` already matches).
|
|
2432
|
-
6. **
|
|
2739
|
+
6. **crew rosters** — for every crew known to the verified or newly minted
|
|
2740
|
+
Scoped Identity, materialize a local strongest-layer skeleton at its resolved
|
|
2741
|
+
`crews/<crew>.json` path. Each new file contains a descriptive `note`, its
|
|
2742
|
+
exact `crew` identity when needed by the bounded filename codec, and
|
|
2743
|
+
`"roster": {}`, so the machine initially inherits the weaker settings and
|
|
2744
|
+
hub layers. Setup never overwrites an existing acceptable crew-roster file:
|
|
2745
|
+
it reports that file as skipped and leaves its bytes untouched. If setup does
|
|
2746
|
+
not know any crews for the identity, it records a non-fatal noted result.
|
|
2747
|
+
7. **plugin** — probe and converge the bundled `owenloop` plugin separately
|
|
2433
2748
|
for Claude Code and Codex. When the installed plugin is missing or its
|
|
2434
2749
|
version differs from the CLI package, setup adds the bundled marketplace
|
|
2435
2750
|
when needed and installs or updates the plugin. Claude Code uses
|
|
@@ -2440,10 +2755,10 @@ plugin version already installed performs no plugin writes. The steps:
|
|
|
2440
2755
|
**Non-fatal:** a missing harness or failed convergence is reported as
|
|
2441
2756
|
`noted` and never fails setup. If the bundled marketplace root is
|
|
2442
2757
|
unavailable, setup prints manual commands instead.
|
|
2443
|
-
|
|
2758
|
+
8. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
|
|
2444
2759
|
the same surfaces, whose result becomes setup's exit code.
|
|
2445
2760
|
|
|
2446
|
-
Progress lines (the `[n/
|
|
2761
|
+
Progress lines (the `[n/8]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
2447
2762
|
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
2448
2763
|
**stdout**.
|
|
2449
2764
|
|
|
@@ -2719,6 +3034,14 @@ inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into
|
|
|
2719
3034
|
which **mints** a new credential directly and therefore stops rather than
|
|
2720
3035
|
ever guessing — a wrong guess there is a side effect a retry cannot undo.
|
|
2721
3036
|
|
|
3037
|
+
For `create_workflow {ephemeral:true}`, the proxy first completes authenticated,
|
|
3038
|
+
non-mutating remote MCP initialization (`initialize`,
|
|
3039
|
+
`notifications/initialized`, then `tools/list`) using the negotiated protocol
|
|
3040
|
+
version and any returned session id. It forwards the create only when the
|
|
3041
|
+
selected hub itself advertises `create_workflow.ephemeral`,
|
|
3042
|
+
`list_workflows.include_ephemeral`, and `delete_workflow`; a proxy-local schema
|
|
3043
|
+
or a 200 inclusive listing is not sufficient evidence.
|
|
3044
|
+
|
|
2722
3045
|
**`~/.owenloop/config.json`** is written by
|
|
2723
3046
|
[`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
|
|
2724
3047
|
JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
|
|
@@ -2731,32 +3054,68 @@ like every other command — an explicit bad value is reported, never silently
|
|
|
2731
3054
|
skipped, precisely because rungs 1–2 come from something the operator typed
|
|
2732
3055
|
or set, not from inference.
|
|
2733
3056
|
|
|
3057
|
+
### Chief-of-staff guidance
|
|
3058
|
+
|
|
3059
|
+
The `initialize` result includes an `instructions` string for MCP hosts. It
|
|
3060
|
+
sets the expected operating posture for the control plane: act as the human's
|
|
3061
|
+
chief of staff, inspect the complete workflow catalog before doing multi-step
|
|
3062
|
+
work, and start a fitting playbook so its crews can execute. Inline step work is
|
|
3063
|
+
appropriate only when no available crew serves the required capability.
|
|
3064
|
+
|
|
3065
|
+
After a run starts or is attended, an MCP client should park on `wake` and call
|
|
3066
|
+
`whats_next` when the returned cursor changes (or when a workflow needs a tick
|
|
3067
|
+
or the human asks for an inbox). The client relays gates, worker asks, receipts,
|
|
3068
|
+
and status to the human; `provide_input` carries human gate answers and
|
|
3069
|
+
`retry_artifact` carries answers to worker `ask` escalations. Rejection is
|
|
3070
|
+
feedback to surface and resolve, not a route to bypass: use `reject_artifact`
|
|
3071
|
+
only for a real upstream defect with a concrete reason.
|
|
3072
|
+
|
|
3073
|
+
The opt-in [MCP chief-of-staff charter evaluation](mcp-charter-eval.md)
|
|
3074
|
+
measures that guidance from structured MCP calls. The current
|
|
3075
|
+
[two-harness baseline](evals/mcp-charter-baseline.json) records the attributable
|
|
3076
|
+
scores, ordered calls, and response evidence. A baseline is replaced only after
|
|
3077
|
+
both credentialed harnesses complete scoreably; it is never fabricated from an
|
|
3078
|
+
incomplete run. The evaluation is quota-spending and not part of required CI.
|
|
3079
|
+
|
|
2734
3080
|
### Tools
|
|
2735
3081
|
|
|
2736
|
-
The server exposes
|
|
3082
|
+
The server exposes 23 baseline tools mirroring the hub's own MCP toolset, plus
|
|
2737
3083
|
`create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
|
|
2738
3084
|
`add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
|
|
2739
|
-
toolset. Each baseline tool's result is the hub REST response as one
|
|
2740
|
-
block; a non-2xx response comes back as an error result.
|
|
3085
|
+
toolset. Each baseline tool's result is the hub REST response unchanged as one
|
|
3086
|
+
text block; a non-2xx response comes back as an error result. The
|
|
3087
|
+
`pending-gates` CLI command likewise prints the hub response unchanged.
|
|
3088
|
+
|
|
3089
|
+
Every `tools/call` validates its arguments against the input schema advertised
|
|
3090
|
+
by `tools/list` before the tool handler runs. An omitted `arguments` member is
|
|
3091
|
+
treated as `{}`; when supplied, `arguments` must be an object and must satisfy
|
|
3092
|
+
the registered schema. A mismatch returns JSON-RPC `-32602` (`INVALID_PARAMS`)
|
|
3093
|
+
and makes no hub request.
|
|
2741
3094
|
|
|
2742
3095
|
| tool | what it does |
|
|
2743
3096
|
|---|---|
|
|
2744
|
-
| `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
|
|
2745
|
-
| `
|
|
2746
|
-
| `
|
|
2747
|
-
| `
|
|
2748
|
-
| `
|
|
2749
|
-
| `
|
|
2750
|
-
| `
|
|
2751
|
-
| `
|
|
3097
|
+
| `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances; optional `serve_capabilities` accepts raw advertised keys |
|
|
3098
|
+
| `pending_gates` | find gates waiting on a human — owed inputs no worker can supply; query after starting or attending runs, or when a human asks what needs attention; optional `serve_crews` narrows the list |
|
|
3099
|
+
| `submit` | return an owed work-order output from a crew member or held-order holder; not a way for a chief of staff to fabricate inline progress |
|
|
3100
|
+
| `reject_artifact` | send a real upstream defect back to its producer with a concrete reason; optional `requested` carries the replacement modifier requested from the producer |
|
|
3101
|
+
| `retry_artifact` | re-arm a stalled or rejected artifact to owed — the human stall-clear, and the answer path for a worker's `ask`; it must not bypass unresolved rejection feedback |
|
|
3102
|
+
| `provide_input` | relay a human answer into a seeded/owed gate |
|
|
3103
|
+
| `start_run` | start a fitting multi-step playbook and let its crews execute; optional `scope` (free routing label, defaults to the session's repo name) and `priority` (`low\|normal\|high`) |
|
|
3104
|
+
| `create_workflow` | parse + load a workflow def YAML when no catalog entry fits and the human chooses authoring; optional `bundle_digest` identifies the content-addressed bundle for reference orders; optional `ephemeral` publishes a retireable one-off only after remote-hub capability attestation |
|
|
3105
|
+
| `get_workflow` | inspect a promising loaded definition before selecting it |
|
|
3106
|
+
| `list_workflows` | discover published workflow definitions and decide which one fits a task; optional `include_ephemeral` includes definitions hidden from the default catalog |
|
|
3107
|
+
| `search_workflows` | context-smaller ranked read of the same published catalog when it is too large to read whole or the host cannot spend the full-list context; requires string `query`, accepts optional positive-integer `limit` and boolean `include_ephemeral`, and returns flattened ranked `{ text, results }`; for smaller catalogs (roughly below 75 definitions), the full listing can support better selection |
|
|
3108
|
+
| `delete_workflow` | retire an ephemeral workflow's live name; the hub refuses while an active root references its exact pinned definition closure |
|
|
2752
3109
|
| `get_status` | `engine.status` verbatim plus a plain-English rendering |
|
|
2753
3110
|
| `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
|
|
2754
3111
|
| `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
|
|
2755
3112
|
| `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
|
|
2756
3113
|
| `publish_event` | publish an event against a contract, starting one run per matched subscription |
|
|
2757
3114
|
| `list_subscriptions` | the org's contract subscriptions |
|
|
2758
|
-
| `presence_ping` | register/refresh this Shift's presence — name, crews served (empty/omitted `serve_crews` means every crew this principal belongs to), and optionally which process incarnation is reporting (`shift_id`/`started_at`); observability only, a separate mechanism from the `heartbeat` lease tool above |
|
|
3115
|
+
| `presence_ping` | register/refresh this Shift's presence — name, crews served (empty/omitted `serve_crews` means every crew this principal belongs to), optional raw `serve_capabilities`, and optionally which process incarnation is reporting (`shift_id`/`started_at`); observability only, a separate mechanism from the `heartbeat` lease tool above |
|
|
2759
3116
|
| `list_shifts` | your principal's registered Shifts — online/offline derived at read time from last ping, crews served (returned as `crews`; empty means every crew this principal belongs to), and each one's reporting incarnation (`shiftId`/`startedAt`) when the hub recorded one |
|
|
3117
|
+
| `get_rosters` | read the org-global and per-crew capability rosters available to this principal |
|
|
3118
|
+
| `list_harness_models` | read the org's registered harnesses, models, and supported efforts |
|
|
2760
3119
|
| `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
|
|
2761
3120
|
| `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
|
|
2762
3121
|
| `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
|
|
@@ -2774,6 +3133,19 @@ message is surfaced verbatim; error bodies never carry tokens). If the store
|
|
|
2774
3133
|
write fails, the result says so and tells you to revoke/re-key the agent from
|
|
2775
3134
|
the console.
|
|
2776
3135
|
|
|
3136
|
+
`start_run`'s `scope` has one default the CLI does not have: when the caller
|
|
3137
|
+
supplies no `scope`, the server fills in the session's repository name, taken
|
|
3138
|
+
from the `origin` remote's URL (its last path segment, trailing `.git`
|
|
3139
|
+
removed) — `owenloop` for
|
|
3140
|
+
`https://github.com/typicalday/owenloop.git`. It is read from the remote rather
|
|
3141
|
+
than the directory name so that every worktree of one repo reports the same
|
|
3142
|
+
scope. It is a default, never an override: an explicitly supplied `scope` is
|
|
3143
|
+
always forwarded unchanged. When no repository name can be determined — not a
|
|
3144
|
+
git checkout, no `origin` remote, an unparseable URL — the server sends no
|
|
3145
|
+
`scope` at all rather than guessing a label. Two repositories with the same
|
|
3146
|
+
name under different owners therefore share a scope; pass an explicit `scope`
|
|
3147
|
+
to tell them apart.
|
|
3148
|
+
|
|
2777
3149
|
**The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
|
|
2778
3150
|
`remove_crew_member`) cover the same four operations as the [`crew` CLI
|
|
2779
3151
|
family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
|
|
@@ -2843,7 +3215,8 @@ interactively.
|
|
|
2843
3215
|
|
|
2844
3216
|
The [`examples/workflows`](../examples/workflows) folder has a workflow per
|
|
2845
3217
|
idea: [`delivery`](../examples/workflows/delivery.yaml) (a review knock-back
|
|
2846
|
-
loop
|
|
3218
|
+
loop — a teaching example, not the production line),
|
|
3219
|
+
[`ship`](../examples/workflows/ship.yaml) (delivery grown up: the full
|
|
2847
3220
|
production line with provisioned workspaces, an adversarial reviewer, a doc
|
|
2848
3221
|
pass, and teardown owned as a step),
|
|
2849
3222
|
[`research`](../examples/workflows/research.yaml) (collections),
|
|
@@ -2877,7 +3250,7 @@ wf=$(owenloop create delivery \
|
|
|
2877
3250
|
run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
|
|
2878
3251
|
owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
|
|
2879
3252
|
|
|
2880
|
-
owenloop status $wf #
|
|
3253
|
+
owenloop status $wf # done / debts / eligible / blocked / pending / inFlight
|
|
2881
3254
|
```
|
|
2882
3255
|
|
|
2883
3256
|
**A knock-back.** When the reviewer's job comes up, instead of greening its
|
|
@@ -2890,7 +3263,9 @@ owenloop reject $wf pr --by reviewer --text "tests are missing"
|
|
|
2890
3263
|
That re-arms `builder` with the reason attached to its next job. Do it past
|
|
2891
3264
|
`builder`'s `maxAttempts` and `pr` **stalls** — owenloop stops re-arming it
|
|
2892
3265
|
and waits for a human. `owenloop retry $wf pr --text "use the new fixture"`
|
|
2893
|
-
clears the stall and resets the counter.
|
|
3266
|
+
clears the stall and resets the counter. `retry --text` is also the answer
|
|
3267
|
+
path for a step that escalated with `ask`; pass `--hub <url>` to answer an
|
|
3268
|
+
ask on a hub-hosted run.
|
|
2894
3269
|
|
|
2895
3270
|
## `reap`, `runs`, and `status.inFlight` — observing and clearing in-flight work
|
|
2896
3271
|
|
|
@@ -2943,6 +3318,12 @@ refuses it. The result JSON is always written to stdout; the human-readable
|
|
|
2943
3318
|
reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
|
|
2944
3319
|
non-zero exit as a failure, not a success.
|
|
2945
3320
|
|
|
3321
|
+
For a bound modifier artifact, local `reject` also accepts
|
|
3322
|
+
`--requested <modifier>`. The engine checks that the requested value is one of
|
|
3323
|
+
the workflow's declared modifiers and carries it in the artifact's next reason
|
|
3324
|
+
thread, where a deterministic producer such as `util modifier-init` can read it.
|
|
3325
|
+
The flag is only valid for an artifact bound to `modifier`.
|
|
3326
|
+
|
|
2946
3327
|
## What a job looks like
|
|
2947
3328
|
|
|
2948
3329
|
`tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
|
|
@@ -2963,6 +3344,7 @@ them.
|
|
|
2963
3344
|
"inputs": ["plan"],
|
|
2964
3345
|
"outputs": ["pr"],
|
|
2965
3346
|
"worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
|
|
3347
|
+
"modifier": "standard", // modifier used for this offer; absent when unmodified
|
|
2966
3348
|
"consumes": { "plan": { /* the accepted input value */ } },
|
|
2967
3349
|
"owes": [ // the feedback channel
|
|
2968
3350
|
{ "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
|
|
@@ -2976,7 +3358,7 @@ A worker first **resolves the reference**: the `(defDigest, step, key)`
|
|
|
2976
3358
|
boundary maps the order to the exact authored instructions from the worker's
|
|
2977
3359
|
trusted local definition source — the same resolver the embedded engine and
|
|
2978
3360
|
the CLI use. Resolution returns the authored `prompt` (with
|
|
2979
|
-
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
|
|
3361
|
+
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MODIFIER}`/`${MAX_ATTEMPTS}`
|
|
2980
3362
|
materialized), the authored `command` if the step has one, and nothing
|
|
2981
3363
|
fabricated. If the worker's source does not know the digest — the definition
|
|
2982
3364
|
was never delivered, or the current on-disk definition no longer matches the
|