owenloop 0.5.9 → 0.5.11
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 +51 -0
- package/README.md +77 -37
- package/bin/owenloop.mjs +16 -1
- package/dist/packages/work/src/agent/loop.js +7 -0
- 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/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 +1 -1
- package/dist/packages/work/src/exec/loop.js +92 -14
- package/dist/packages/work/src/harness/claude.js +16 -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/roles/agent-run.js +38 -10
- package/dist/packages/work/src/roles/exec.js +25 -8
- package/dist/packages/work/src/shift/loop.js +118 -4
- package/dist/packages/work/src/shift/runtime.d.ts +3 -0
- package/dist/packages/work/src/shift/runtime.js +10 -1
- package/dist/packages/work/src/submit-proof.d.ts +11 -8
- package/dist/packages/work/src/submit-proof.js +11 -8
- package/dist/src/capabilities.d.ts +70 -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 +2 -2
- package/dist/src/cli.js +1200 -166
- package/dist/src/defs.d.ts +41 -1
- package/dist/src/defs.js +461 -92
- package/dist/src/engine.d.ts +108 -22
- package/dist/src/engine.js +573 -85
- package/dist/src/factory.js +5 -3
- package/dist/src/hub.d.ts +77 -0
- package/dist/src/hub.js +162 -0
- package/dist/src/implements.d.ts +37 -0
- package/dist/src/implements.js +790 -0
- package/dist/src/index.d.ts +12 -10
- package/dist/src/index.js +7 -6
- package/dist/src/mcp/serve.js +254 -45
- package/dist/src/mcp/server.d.ts +10 -7
- package/dist/src/mcp/server.js +53 -8
- package/dist/src/model.d.ts +46 -10
- package/dist/src/model.js +224 -78
- package/dist/src/order-resolver.js +1 -0
- 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 +563 -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 +66 -4
- package/dist/src/store.js +333 -12
- package/dist/src/types.d.ts +97 -17
- package/dist/src/types.js +4 -0
- package/dist/src/util.js +4 -1
- package/docs/authoring.md +214 -9
- package/docs/bundles.md +19 -0
- package/docs/cli.md +270 -30
- package/docs/crypto.md +13 -7
- package/docs/design.md +107 -46
- package/docs/evals/mcp-charter-baseline.json +428 -0
- package/docs/mcp-charter-eval.md +124 -0
- package/docs/shift-logs.md +18 -0
- package/docs/wire-contracts.md +28 -7
- package/examples/workflows/compile-dev-playbook.yaml +1 -1
- package/examples/workflows/ship.yaml +28 -2
- 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) |
|
|
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 |
|
|
56
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) |
|
|
@@ -86,7 +107,7 @@ for the full breakdown.
|
|
|
86
107
|
| `util modifier-init --default <value>` | choose a modifier from rejection feedback, the order hint, or a default; intended for command steps |
|
|
87
108
|
| `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
|
|
88
109
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
89
|
-
| `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 |
|
|
90
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 |
|
|
91
112
|
| `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
|
|
92
113
|
| `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
|
|
@@ -97,7 +118,7 @@ for the full breakdown.
|
|
|
97
118
|
| `green <wf> <run> <path> [--value json] [--terminal]` | accept an owed output |
|
|
98
119
|
| `emit <wf> <run> --items '[{…},{…}]'` | add collection elements |
|
|
99
120
|
| `seal <wf> <run> [--value json]` | mark a collection complete |
|
|
100
|
-
| `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 |
|
|
101
122
|
| `retract <wf> <path> --by <author> --text <msg>` | drop a collection member |
|
|
102
123
|
| `skip <wf> <path> --by <author> --text <msg>` | a step declines its own output |
|
|
103
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 |
|
|
@@ -105,10 +126,27 @@ for the full breakdown.
|
|
|
105
126
|
| `delete <wf>` | delete an instance and all its rows |
|
|
106
127
|
| `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
|
|
107
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
|
+
|
|
108
146
|
## Bundles
|
|
109
147
|
|
|
110
|
-
|
|
111
|
-
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`
|
|
112
150
|
read or write only the paths named by the command; they do not create
|
|
113
151
|
`.owenloop/state.db`, contact a remote coordinator, or use workflow definitions
|
|
114
152
|
from `--defs`. Successful commands print one JSON object on stdout. Failures
|
|
@@ -119,8 +157,60 @@ owenloop bundle pack <source-dir> [--output <bundle.wnlp>]
|
|
|
119
157
|
owenloop bundle unpack <bundle.wnlp> <destination-dir>
|
|
120
158
|
owenloop bundle inspect <bundle.wnlp>
|
|
121
159
|
owenloop bundle digest <bundle.wnlp>
|
|
160
|
+
owenloop bundle gc [--keep <n>] [--global] [--yes]
|
|
122
161
|
```
|
|
123
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
|
+
|
|
124
214
|
`pack` requires a source directory containing root `bundle.yaml` and every
|
|
125
215
|
workflow path listed by the manifest's `workflows` map. The source manifest is
|
|
126
216
|
not modified. If `--output` is omitted,
|
|
@@ -223,6 +313,16 @@ one loop sweep and exits instead of keeping the foreground daemon running.
|
|
|
223
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 |
|
|
224
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 |
|
|
225
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
|
+
|
|
226
326
|
**On-disk logs.** A running shift appends its dispatch record to
|
|
227
327
|
`<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
|
|
228
328
|
and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
|
|
@@ -665,11 +765,11 @@ separate concern.
|
|
|
665
765
|
`owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
|
|
666
766
|
`workflows/**` folder (via GitHub's REST API and Node's built-in `fetch` — no
|
|
667
767
|
new dependency), validates every def with the same lint/validate/`check`
|
|
668
|
-
machinery `owenloop lint`/`owenloop check` use
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
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
|
|
673
773
|
characters of `sha256(owner/repo)`. The hash keeps distinct sources that used
|
|
674
774
|
to collide on the same `<owner>-<repo>` folder (e.g. `a-b/c` and `a/b-c`)
|
|
675
775
|
from clobbering each other. `owner` and `repo` are restricted to the
|
|
@@ -813,16 +913,25 @@ defs dir is guarded only on the default `cwd/workflows` fallback — an explicit
|
|
|
813
913
|
matching the `--db`/`OWENLOOP_DB` rule above.
|
|
814
914
|
|
|
815
915
|
**Installed-def discovery.** Defs installed by `add` are discovered by default:
|
|
816
|
-
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
|
|
817
917
|
(`cwd/workflows`) sees them by name, no `--defs` flag needed. `loadDefs` itself
|
|
818
918
|
stays a pure dir-scanner (top-level `*.yaml` plus immediate-subdir
|
|
819
919
|
`workflow.yaml`); the CLI folds installed subfolders in on top, ledger-driven and
|
|
820
920
|
bounded — it only loads folders named by the fail-closed-validated
|
|
821
921
|
`.owenloop/installed.json` entries, never a raw recurse of the tree.
|
|
822
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
|
+
|
|
823
931
|
- **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
|
|
824
932
|
operator intent to target a literal dir and keeps the pure-scan behavior with
|
|
825
|
-
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",
|
|
826
935
|
so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
|
|
827
936
|
Pointing `--defs` straight at an install folder
|
|
828
937
|
(`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
|
|
@@ -833,9 +942,12 @@ bounded — it only loads folders named by the fail-closed-validated
|
|
|
833
942
|
- **Fail-open.** The fold-in never breaks base loading. A corrupt or
|
|
834
943
|
structurally-invalid `installed.json`, a missing install folder, or an install
|
|
835
944
|
folder that fails to load each emits a `warning:` on stderr and is skipped;
|
|
836
|
-
your project defs still load and
|
|
837
|
-
|
|
838
|
-
|
|
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.
|
|
839
951
|
|
|
840
952
|
Public repos only — no auth/token support yet; a private repo (or a bad
|
|
841
953
|
ref) surfaces as a 404 from the sha-resolve step.
|
|
@@ -1565,6 +1677,14 @@ stream cancelled) rather than buffered, closing the same memory-exhaustion gap
|
|
|
1565
1677
|
on the hub path that the `add` download cap closes on the archive path.
|
|
1566
1678
|
`OWENLOOP_HUB_MAX_RESPONSE_BYTES` overrides the cap (a test knob).
|
|
1567
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
|
+
|
|
1568
1688
|
### `login` — authenticate the CLI against a hub
|
|
1569
1689
|
|
|
1570
1690
|
Two ways to get a credential, both of which **verify before storing** (a token
|
|
@@ -1842,6 +1962,18 @@ On a `401`, an OAuth credential is refreshed once and the request retried; an
|
|
|
1842
1962
|
agent (`olp_`) token has no refresh path, so a `401` is a hard "re-mint it"
|
|
1843
1963
|
error.
|
|
1844
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
|
+
|
|
1845
1977
|
**Include and bodyFile limitations.** A def whose file uses `include:` is
|
|
1846
1978
|
refused (`uses include:, not hub-pushable`): the hub's `create_workflow`
|
|
1847
1979
|
parses the raw YAML without include expansion, and a re-serialized expanded
|
|
@@ -1850,6 +1982,73 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
|
|
|
1850
1982
|
resolve the external file against once the YAML leaves this machine. Inline
|
|
1851
1983
|
both before pushing.
|
|
1852
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
|
+
|
|
1853
2052
|
### `publish` — pack and publish a workflow bundle
|
|
1854
2053
|
|
|
1855
2054
|
```text
|
|
@@ -2835,6 +3034,14 @@ inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into
|
|
|
2835
3034
|
which **mints** a new credential directly and therefore stops rather than
|
|
2836
3035
|
ever guessing — a wrong guess there is a side effect a retry cannot undo.
|
|
2837
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
|
+
|
|
2838
3045
|
**`~/.owenloop/config.json`** is written by
|
|
2839
3046
|
[`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
|
|
2840
3047
|
JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
|
|
@@ -2847,25 +3054,58 @@ like every other command — an explicit bad value is reported, never silently
|
|
|
2847
3054
|
skipped, precisely because rungs 1–2 come from something the operator typed
|
|
2848
3055
|
or set, not from inference.
|
|
2849
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
|
+
|
|
2850
3080
|
### Tools
|
|
2851
3081
|
|
|
2852
|
-
The server exposes
|
|
3082
|
+
The server exposes 23 baseline tools mirroring the hub's own MCP toolset, plus
|
|
2853
3083
|
`create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
|
|
2854
3084
|
`add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
|
|
2855
|
-
toolset. Each baseline tool's result is the hub REST response as one
|
|
2856
|
-
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.
|
|
2857
3094
|
|
|
2858
3095
|
| tool | what it does |
|
|
2859
3096
|
|---|---|
|
|
2860
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 |
|
|
2861
|
-
| `
|
|
2862
|
-
| `
|
|
2863
|
-
| `
|
|
2864
|
-
| `
|
|
2865
|
-
| `
|
|
2866
|
-
| `
|
|
2867
|
-
| `
|
|
2868
|
-
| `
|
|
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 |
|
|
2869
3109
|
| `get_status` | `engine.status` verbatim plus a plain-English rendering |
|
|
2870
3110
|
| `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
|
|
2871
3111
|
| `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
|
package/docs/crypto.md
CHANGED
|
@@ -174,13 +174,19 @@ consumer passes to `verifyConsumed` as `expectedVersion`. It is never inferred
|
|
|
174
174
|
from process-local state.
|
|
175
175
|
|
|
176
176
|
Retry-safety is a property of where the target is computed, not of the client.
|
|
177
|
-
The engine
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
177
|
+
The engine issues it inside the claim transaction and persists it with the
|
|
178
|
+
order, so a reconnect, a retried submit after a lost response, or a restarted
|
|
179
|
+
holder re-reads the issued number instead of guessing one; a refinement is a new
|
|
180
|
+
claim and receives a newly issued target.
|
|
181
|
+
|
|
182
|
+
The target is not frozen for the life of the claim. A refusal that leaves the
|
|
183
|
+
run open without bumping the artifact (a schema reject) leaves it correct, but a
|
|
184
|
+
judgment or human reject follows a commit that already bumped the artifact and
|
|
185
|
+
leaves the same claim live to retry — so the engine re-stamps that claim's
|
|
186
|
+
target from the current committed version at the reject site. A client must
|
|
187
|
+
therefore re-read `owes[].version` off the order on every submit and never cache
|
|
188
|
+
it across a reject. A stale target fails the consumer's version check, which is
|
|
189
|
+
a refusal, never an admitted unverified value.
|
|
184
190
|
|
|
185
191
|
A target is authoritative only when it is a positive integer: the smallest
|
|
186
192
|
commit any producer can land is v1. An absent target, a `0`, or a non-integer
|