owenloop 0.4.1 → 0.5.1
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 +71 -0
- package/README.md +182 -53
- package/bin/owenloop.mjs +50 -2
- package/dist/packages/work/src/agent/brief.d.ts +176 -0
- package/dist/packages/work/src/agent/brief.js +197 -0
- package/dist/packages/work/src/agent/loop.d.ts +141 -0
- package/dist/packages/work/src/agent/loop.js +669 -0
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +92 -0
- package/dist/packages/work/src/bundle/cache.js +338 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
- package/dist/packages/work/src/bundle/fetch.js +345 -0
- package/dist/packages/work/src/bundle/types.d.ts +164 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
- package/dist/packages/work/src/consumed-verifier.js +205 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/instructions.d.ts +99 -0
- package/dist/packages/work/src/exec/instructions.js +323 -0
- package/dist/packages/work/src/exec/loop.d.ts +40 -0
- package/dist/packages/work/src/exec/loop.js +332 -0
- package/dist/packages/work/src/exec/payload.d.ts +29 -0
- package/dist/packages/work/src/exec/payload.js +54 -0
- package/dist/packages/work/src/exec/receipt.d.ts +41 -0
- package/dist/packages/work/src/exec/receipt.js +32 -0
- package/dist/packages/work/src/exec/runner.d.ts +71 -0
- package/dist/packages/work/src/exec/runner.js +256 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +134 -0
- package/dist/packages/work/src/harness/claude.d.ts +140 -0
- package/dist/packages/work/src/harness/claude.js +837 -0
- package/dist/packages/work/src/harness/codex.d.ts +111 -0
- package/dist/packages/work/src/harness/codex.js +1024 -0
- package/dist/packages/work/src/harness/contract.d.ts +308 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +91 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
- package/dist/packages/work/src/harness/permissions.d.ts +75 -0
- package/dist/packages/work/src/harness/permissions.js +182 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +181 -0
- package/dist/packages/work/src/harness/session-store.js +523 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +75 -0
- package/dist/packages/work/src/hold/mcp.js +264 -0
- package/dist/packages/work/src/hub/client.d.ts +23 -0
- package/dist/packages/work/src/hub/client.js +91 -0
- package/dist/packages/work/src/hub/types.d.ts +326 -0
- package/dist/packages/work/src/hub/types.js +26 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
- package/dist/packages/work/src/owenloop-bin.js +18 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
- package/dist/packages/work/src/roles/agent-run.js +529 -0
- package/dist/packages/work/src/roles/exec.d.ts +48 -0
- package/dist/packages/work/src/roles/exec.js +228 -0
- package/dist/packages/work/src/roles/hold.d.ts +72 -0
- package/dist/packages/work/src/roles/hold.js +363 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +58 -0
- package/dist/packages/work/src/roles/lint.js +234 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +71 -0
- package/dist/packages/work/src/roles/shift.d.ts +13 -0
- package/dist/packages/work/src/roles/shift.js +250 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +136 -0
- package/dist/packages/work/src/settings/settings.js +155 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +131 -0
- package/dist/packages/work/src/shift/loop.js +751 -0
- package/dist/packages/work/src/shift/protocol.d.ts +95 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +45 -0
- package/dist/packages/work/src/shift/runtime.js +337 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +109 -0
- package/dist/packages/work/src/shift/spawn.js +158 -0
- package/dist/packages/work/src/shift/state.d.ts +79 -0
- package/dist/packages/work/src/shift/state.js +385 -0
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/src/add.d.ts +189 -0
- package/dist/src/add.js +300 -0
- package/dist/src/archive.d.ts +97 -0
- package/dist/src/archive.js +591 -0
- package/dist/src/bundle/index.d.ts +64 -0
- package/dist/src/bundle/index.js +508 -0
- package/dist/src/bundle/manifest.d.ts +50 -0
- package/dist/src/bundle/manifest.js +435 -0
- package/dist/src/bundle/runtime.d.ts +26 -0
- package/dist/src/bundle/runtime.js +64 -0
- package/dist/src/bundle/tar.d.ts +62 -0
- package/dist/src/bundle/tar.js +238 -0
- package/dist/src/bundle/types.d.ts +105 -0
- package/dist/src/bundle/types.js +21 -0
- package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
- package/dist/src/cli.js +5968 -0
- package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
- package/dist/{credentials.js → src/credentials.js} +35 -31
- package/dist/src/crypto/allowed-signers.d.ts +68 -0
- package/dist/src/crypto/allowed-signers.js +307 -0
- package/dist/src/crypto/canonical.d.ts +8 -0
- package/dist/src/crypto/canonical.js +92 -0
- package/dist/src/crypto/chain.d.ts +65 -0
- package/dist/src/crypto/chain.js +377 -0
- package/dist/src/crypto/dsse.d.ts +209 -0
- package/dist/src/crypto/dsse.js +282 -0
- package/dist/src/crypto/enrollment.d.ts +78 -0
- package/dist/src/crypto/enrollment.js +186 -0
- package/dist/src/crypto/index.d.ts +48 -0
- package/dist/src/crypto/index.js +44 -0
- package/dist/src/crypto/keys.d.ts +258 -0
- package/dist/src/crypto/keys.js +908 -0
- package/dist/src/crypto/org-root.d.ts +33 -0
- package/dist/src/crypto/org-root.js +78 -0
- package/dist/src/crypto/origin-rules.d.ts +56 -0
- package/dist/src/crypto/origin-rules.js +143 -0
- package/dist/src/crypto/policy-floor.d.ts +98 -0
- package/dist/src/crypto/policy-floor.js +353 -0
- package/dist/src/crypto/records.d.ts +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
- package/dist/{defs.js → src/defs.js} +181 -61
- package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
- package/dist/{engine.js → src/engine.js} +251 -47
- package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
- package/dist/{factory.js → src/factory.js} +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
- package/dist/{hub.js → src/hub.js} +493 -52
- package/dist/src/index.d.ts +47 -0
- package/dist/src/index.js +41 -0
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +38 -0
- package/dist/src/lock.js +325 -0
- package/dist/src/mcp/serve.d.ts +109 -0
- package/dist/{mcp → src/mcp}/serve.js +335 -75
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +18 -10
- package/dist/{model.d.ts → src/model.d.ts} +15 -0
- package/dist/{model.js → src/model.js} +112 -2
- package/dist/src/order-resolver.d.ts +184 -0
- package/dist/src/order-resolver.js +252 -0
- package/dist/src/package-version.d.ts +10 -0
- package/dist/src/package-version.js +42 -0
- package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
- package/dist/{paths.js → src/paths.js} +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/{types.d.ts → src/types.d.ts} +58 -24
- package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
- package/dist/src/untar.js +38 -0
- package/dist/{util.d.ts → src/util.d.ts} +3 -2
- package/dist/{util.js → src/util.js} +3 -2
- package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
- package/dist/{owenwork.js → src/work-settings.js} +27 -27
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +150 -59
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1758 -163
- package/docs/crypto.md +816 -0
- package/docs/design.md +374 -52
- package/docs/embedding.md +135 -27
- package/docs/wire-contracts.md +380 -0
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +22 -8
- package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
- package/plugins/claude-code/plugin/.mcp.json +14 -0
- package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
- package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
- package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
- package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
- package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
- package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
- package/plugins/codex/.agents/plugins/marketplace.json +21 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
- package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
- package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
- package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
- package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
- package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
- package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
- package/dist/add.d.ts +0 -384
- package/dist/add.js +0 -834
- package/dist/cli.js +0 -3270
- package/dist/index.d.ts +0 -32
- package/dist/index.js +0 -23
- package/dist/lock.d.ts +0 -80
- package/dist/lock.js +0 -217
- package/dist/mcp/serve.d.ts +0 -84
- package/dist/untar.js +0 -164
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
package/docs/cli.md
CHANGED
|
@@ -22,10 +22,10 @@ prints this usage and exits 0 without doing any work.
|
|
|
22
22
|
|
|
23
23
|
Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
|
|
24
24
|
`--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
|
|
25
|
-
`--strict-inputs`, and the bare `--now` on `reap`) never take a
|
|
26
|
-
value — the next token is always a positional or the next `--flag`,
|
|
27
|
-
consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>`
|
|
28
|
-
`tick`) for flags that do take a value.
|
|
25
|
+
`--strict-inputs`, `--unsigned`, and the bare `--now` on `reap`) never take a
|
|
26
|
+
following value — the next token is always a positional or the next `--flag`,
|
|
27
|
+
never consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>`
|
|
28
|
+
on `tick`) for flags that do take a value.
|
|
29
29
|
|
|
30
30
|
`owenloop check <def>` defaults to treating `seedOwed` inputs as provided
|
|
31
31
|
(`assumeProvided: true`), so a def whose only initial gate is an unprovided
|
|
@@ -44,18 +44,37 @@ for the full breakdown.
|
|
|
44
44
|
|---|---|
|
|
45
45
|
| `defs` | list available workflow definitions |
|
|
46
46
|
| `add <owner>/<repo>[@ref]` | fetch, validate, and install a repo's workflow defs from GitHub (public repos only) — see below |
|
|
47
|
-
| `add --
|
|
47
|
+
| `add <bundle.wnlp \| https://url> [--global]` | install a workflow bundle into the content-addressed store — project store under the defs dir by default, `<home>/.owenloop/workflows` with `--global` — see below |
|
|
48
|
+
| `add --recover [--global]` | finish or undo a crash-interrupted install, offline — no network call (`--global` recovers the global store) — see below |
|
|
49
|
+
| `bundle pack <source-dir> [--output <bundle.wnlp>]` | create a deterministic `.wnlp` package without opening the local store — see [Bundles](#bundles) |
|
|
50
|
+
| `bundle unpack <bundle.wnlp> <destination-dir>` | strictly validate and atomically extract a `.wnlp` package — see [Bundles](#bundles) |
|
|
51
|
+
| `bundle inspect <bundle.wnlp>` | strictly validate a `.wnlp` package and print its manifest and file metadata — see [Bundles](#bundles) |
|
|
52
|
+
| `bundle digest <bundle.wnlp>` | print the SHA-256 digest of the uncompressed canonical tar — see [Bundles](#bundles) |
|
|
48
53
|
| `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) |
|
|
49
|
-
| `connect [--hub <url>] [--as <slot>]` |
|
|
50
|
-
| `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the
|
|
54
|
+
| `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
|
+
| `start <defName> [--provide name=json …] [--crew <name>] [--title <text>] [--hub <url>]` | start a published workflow on the bound hub with the human credential |
|
|
57
|
+
| `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 |
|
|
51
58
|
| `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
|
|
52
|
-
| `agent new <name> [--
|
|
53
|
-
| `
|
|
59
|
+
| `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) |
|
|
60
|
+
| `capability bind <capability> <crew> [--hub <url>]` | add a crew to a workflow capability on the hub org — a capability may route to many crews (admin; human credential) — see [Capability routes](#capability-routes) |
|
|
61
|
+
| `capability unbind <capability> <crew> [--hub <url>]` | remove one `(capability, crew)` route — see [Capability routes](#capability-routes) |
|
|
62
|
+
| `capability list [--hub <url>]` | list the hub org's capability routes — see [Capability routes](#capability-routes) |
|
|
63
|
+
| `crew list [--hub <url>]` | list the hub org's crews with their members (includes the orphan crew once one exists) — see [Crews](#crews) |
|
|
64
|
+
| `crew new <name> --kind personal\|shared [--owner <memberId>] [--hub <url>]` | create a crew on the hub org (admin, or own personal crew; human credential) — see [Crews](#crews) |
|
|
65
|
+
| `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
|
|
66
|
+
| `crew member add <crewId> <principalKind> <principalId> [--hub <url>]` | add a member or agent to a crew — see [Crews](#crews) |
|
|
67
|
+
| `crew member rm <crewId> <principalId> [--hub <url>]` | remove a principal from a crew — see [Crews](#crews) |
|
|
68
|
+
| `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) |
|
|
69
|
+
| `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) |
|
|
54
70
|
| `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
|
|
55
71
|
| `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) |
|
|
72
|
+
| `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) |
|
|
73
|
+
| `work <subcommand> [options]` | run the execution-side CLI companion — see [`work`](#work--execution-side-cli-companion) |
|
|
74
|
+
| `trust init\|grant\|revoke` | create and sign local enrollment trust records offline — see [`trust`](#trust--local-enrollment-trust) |
|
|
56
75
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
57
76
|
| `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
|
|
58
|
-
| `tick <wf> [--now=<ms>] [--shallow] [--
|
|
77
|
+
| `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 |
|
|
59
78
|
| `reap <wf> [--now]` | run the reaper; `--now` forces every claim stale (TTL 0) — see below |
|
|
60
79
|
| `runs <wf> [--open]` | list this instance's runs, joining claim state for open ones |
|
|
61
80
|
| `status <wf>` | derived view: `done`, `debts`, `eligible`, `blocked`, `inFlight` |
|
|
@@ -73,6 +92,342 @@ for the full breakdown.
|
|
|
73
92
|
| `delete <wf>` | delete an instance and all its rows |
|
|
74
93
|
| `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
|
|
75
94
|
|
|
95
|
+
## Bundles
|
|
96
|
+
|
|
97
|
+
Bundle commands are deliberately dispatched before the CLI opens the engine
|
|
98
|
+
store. `bundle pack`, `bundle inspect`, `bundle digest`, and `bundle unpack`
|
|
99
|
+
read or write only the paths named by the command; they do not create
|
|
100
|
+
`.owenloop/state.db`, contact a remote coordinator, or use workflow definitions
|
|
101
|
+
from `--defs`. Successful commands print one JSON object on stdout. Failures
|
|
102
|
+
print a diagnostic on stderr and exit nonzero.
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
owenloop bundle pack <source-dir> [--output <bundle.wnlp>]
|
|
106
|
+
owenloop bundle unpack <bundle.wnlp> <destination-dir>
|
|
107
|
+
owenloop bundle inspect <bundle.wnlp>
|
|
108
|
+
owenloop bundle digest <bundle.wnlp>
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`pack` requires a source directory containing root `bundle.yaml` and every
|
|
112
|
+
workflow path listed by the manifest's `workflows` map. The source manifest is
|
|
113
|
+
not modified. If `--output` is omitted,
|
|
114
|
+
the output is `<package-name>-<version>.wnlp` next to the source directory. An
|
|
115
|
+
explicit output path must be outside the source directory. A regular file at
|
|
116
|
+
the output path may be replaced; a directory or other non-regular path is
|
|
117
|
+
rejected.
|
|
118
|
+
|
|
119
|
+
A format-v2 source manifest may declare the optional closed `runtime` mapping
|
|
120
|
+
documented in [`docs/bundles.md`](bundles.md#runtime-compatibility). `pack`
|
|
121
|
+
validates the current Owenloop version and advertised features before loading
|
|
122
|
+
usable workflows. When the declaration is present, successful pack JSON includes
|
|
123
|
+
a `runtime` property with `minVersion` before canonically UTF-8-sorted
|
|
124
|
+
`features`. When the declaration is absent, pack JSON does not gain a `runtime`
|
|
125
|
+
property; existing output remains unchanged.
|
|
126
|
+
|
|
127
|
+
`inspect` performs bounded gzip inflation, strict POSIX/PAX tar validation,
|
|
128
|
+
manifest and runtime-admission validation, workflow validation, lock coverage
|
|
129
|
+
checks, and per-file integrity checks without extracting files. Inspect JSON's
|
|
130
|
+
`manifest` includes `runtime` only when the archive declares it. A malformed
|
|
131
|
+
runtime declaration fails with `MANIFEST_ERROR`; a valid declaration requiring
|
|
132
|
+
a newer version or unsupported feature fails with `RUNTIME_INCOMPATIBLE` and
|
|
133
|
+
install/upgrade guidance.
|
|
134
|
+
|
|
135
|
+
`digest` performs bounded inflation and returns the lowercase SHA-256 of the
|
|
136
|
+
exact uncompressed canonical tar; the gzip wrapper bytes are not the identity.
|
|
137
|
+
`digest` is identity-only: it does not parse the manifest and may therefore
|
|
138
|
+
succeed for a canonical bundle that this Owenloop process cannot inspect,
|
|
139
|
+
unpack, install, load, or execute.
|
|
140
|
+
|
|
141
|
+
`unpack` performs the complete `inspect` validation before creating anything.
|
|
142
|
+
The destination must be absent. Files are written into a fresh sibling staging
|
|
143
|
+
directory and the staging directory is renamed into place only after all files
|
|
144
|
+
are written. Existing symlinked destination ancestors are rejected.
|
|
145
|
+
|
|
146
|
+
The manifest and archive rules are documented in
|
|
147
|
+
[`docs/bundles.md`](bundles.md). The public in-process equivalents are
|
|
148
|
+
`packBundle`, `inspectBundle`, `digestBundle`, and `unpackBundle` from the
|
|
149
|
+
package barrel.
|
|
150
|
+
|
|
151
|
+
## `shift` — foreground daemon and client
|
|
152
|
+
|
|
153
|
+
`owenloop shift` is the public local dispatch surface. `shift start` runs the
|
|
154
|
+
self-driven dispatch loop as a foreground process and listens on
|
|
155
|
+
`<stateDir>/shift.sock`. Each client connection carries one JSON-line request
|
|
156
|
+
and one JSON-line response. The daemon keeps polling and dispatching while no
|
|
157
|
+
`shift next` client is attached.
|
|
158
|
+
|
|
159
|
+
The public daemon transport is supported on macOS and Linux. Windows support is
|
|
160
|
+
explicitly limited to the direct `owenloop work shift` loop: the public
|
|
161
|
+
`owenloop shift start|next|status|end` daemon is unavailable because Windows
|
|
162
|
+
named-pipe transport has not been implemented. A Windows daemon start fails
|
|
163
|
+
with that diagnostic instead of treating a Unix-domain socket path as usable.
|
|
164
|
+
|
|
165
|
+
The `shift start` positional argument is a **crew** name. The routing API calls
|
|
166
|
+
that field a **crew**: `serve_crews` contains the selected crew names. Passing
|
|
167
|
+
`--all` maps to an empty `serve_crews` list, which means all crews available to
|
|
168
|
+
the Scoped Identity. Do not treat `attended_at` as a liveness signal: every
|
|
169
|
+
accepted `shift next` records attendance and makes the next presence ping due,
|
|
170
|
+
but attendance is advisory and observability-only. Attendance never changes
|
|
171
|
+
routing, dispatch, or lease behavior.
|
|
172
|
+
|
|
173
|
+
The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
174
|
+
`XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
|
|
175
|
+
`$HOME/.config/owenloop/settings.json`.
|
|
176
|
+
|
|
177
|
+
### `shift start <crew...>`
|
|
178
|
+
|
|
179
|
+
```text
|
|
180
|
+
owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
|
|
181
|
+
[--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
|
|
182
|
+
[--cache-dir <p>] [--state-dir <p>]
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
At least one named crew is required unless `--all` is present. `--all` and
|
|
186
|
+
named crews are mutually exclusive. Duplicate named crews collapse to one
|
|
187
|
+
entry before routing. The daemon owns one socket at a time; a second start
|
|
188
|
+
against the same socket is refused. There is no detach mode. `--once` performs
|
|
189
|
+
one loop sweep and exits instead of keeping the foreground daemon running.
|
|
190
|
+
|
|
191
|
+
| option | default and behavior |
|
|
192
|
+
|---|---|
|
|
193
|
+
| `--origin <url>` | use this hub origin; otherwise use `hubOrigin` from the execution settings file; there is no hub-origin fallback |
|
|
194
|
+
| `--as <account>` | use this Scoped Identity account; defaults to `default` |
|
|
195
|
+
| `--name <n>` | use this shift name; otherwise generate one from the host and current directory with a process/shift suffix |
|
|
196
|
+
| `--cap <n>` | dispatch capacity; precedence is flag, then `settings.dispatchCap`, then `3` |
|
|
197
|
+
| `--max-agents <n>` | concurrent agent limit; precedence is flag, then `settings.maxConcurrentAgents`, then `4` |
|
|
198
|
+
| `--poll-interval <ms>` | loop polling interval; defaults to `5000` milliseconds |
|
|
199
|
+
| `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
|
|
200
|
+
| `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
|
|
201
|
+
| `--state-dir <p>` | socket and child-state root; precedence is flag, then `OWENLOOP_STATE_DIR`, then `settings.stateDir`, then `$XDG_STATE_HOME/owenloop/exec`, then `$HOME/.local/state/owenloop/exec`; the socket is `shift.sock` inside this directory |
|
|
202
|
+
|
|
203
|
+
A clean start or `--once` completion exits `0`. `owenloop shift --help` also
|
|
204
|
+
exits `0`. Runtime failures such as credential reads or socket/runtime setup
|
|
205
|
+
exit `1`. Usage and
|
|
206
|
+
precondition failures — including no crew or `--all`, invalid flags, a missing
|
|
207
|
+
hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
|
|
208
|
+
daemon's normal lifecycle line is written to stdout when it stays running;
|
|
209
|
+
diagnostics go to stderr.
|
|
210
|
+
|
|
211
|
+
**Dispatch-state safety.** Every current-version direct Shift loop that shares a
|
|
212
|
+
state directory serializes the capacity recheck and durable reservation under
|
|
213
|
+
the same `.dispatch.lock`. The lock is released before process spawn; the per-run
|
|
214
|
+
reservation carries the capacity slot through spawn and PID persistence. Two
|
|
215
|
+
current-version loops therefore cannot both consume the same last slot, and a
|
|
216
|
+
loop that loses the shared-capacity race keeps its already-claimed candidate in
|
|
217
|
+
its local queue. Older Shift loops that predate `.dispatch.lock` do not
|
|
218
|
+
participate in that boundary and must not share the state directory during the
|
|
219
|
+
upgrade. The state directory does not persist one canonical cap: if current-
|
|
220
|
+
version loops sharing the directory are configured with different total or
|
|
221
|
+
agent caps, each loop enforces its own configured limits under the shared lock.
|
|
222
|
+
Use identical cap settings for every loop sharing a state directory.
|
|
223
|
+
|
|
224
|
+
Canonical `*.json` child and reservation records are capacity-bearing state.
|
|
225
|
+
Missing records are benign, including a record that disappears between listing
|
|
226
|
+
and read. A truncated, malformed, or unreadable canonical record is not benign:
|
|
227
|
+
reconciliation fails closed, names the exact path, and disables dispatch until
|
|
228
|
+
an operator repairs the record or removes the record after verifying that no
|
|
229
|
+
child still owns the slot. Owenloop does not skip corrupt records and guess that
|
|
230
|
+
capacity is free. Reconciliation also cancels a reservation when the worker has
|
|
231
|
+
removed its gate after the worker's monotonic two-minute wait, regardless of the
|
|
232
|
+
persisted wall-clock age. A reservation timestamp later than the current wall
|
|
233
|
+
clock is cancelled along with its closed start gate.
|
|
234
|
+
|
|
235
|
+
Persisted reservation age still uses wall time because a monotonic instant cannot
|
|
236
|
+
be reconstructed after a host restart. A smaller backward clock adjustment that
|
|
237
|
+
leaves `reservedAt` in the past can therefore prolong a reservation whose gate
|
|
238
|
+
still exists, such as a parent crash before spawn. The reservation remains
|
|
239
|
+
capacity-bearing until wall time reaches the age limit or an operator verifies
|
|
240
|
+
that no child can start and removes the record and gate. This limitation cannot
|
|
241
|
+
allow provider or command work past the gate: a spawned child independently
|
|
242
|
+
removes the gate and exits after its monotonic two-minute wait.
|
|
243
|
+
|
|
244
|
+
### `shift next [--wait <seconds>]`
|
|
245
|
+
|
|
246
|
+
```text
|
|
247
|
+
owenloop shift next [--wait <seconds>] [--state-dir <p>]
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
`--wait` accepts a finite, non-negative number of seconds and defaults to `90`.
|
|
251
|
+
`--state-dir` selects the daemon socket. Only one `next` call may be parked at
|
|
252
|
+
a time. A second parked call returns this error and exits `1`:
|
|
253
|
+
|
|
254
|
+
```text
|
|
255
|
+
whats_next is already parked — one park at a time (cancel it or wait for it to return)
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
When a `next` request is accepted, the daemon stamps `attended_at`. The call
|
|
259
|
+
returns promptly when an event is queued, the wait expires, or the shift
|
|
260
|
+
explicitly ends. A normal timeout exits `0` and prints the current capacity
|
|
261
|
+
object, for example `{ "cap": 3, "free": 3, "running": 0, "events": [] }`.
|
|
262
|
+
Successful responses use the same capacity shape and may include queued event
|
|
263
|
+
objects. For `dispatched`, `reaped`, and `failed`, `kind` is either `exec` or
|
|
264
|
+
`agent-run`:
|
|
265
|
+
|
|
266
|
+
- `dispatched`: `{ "type": "dispatched", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "pid": 123 }`
|
|
267
|
+
- `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
|
|
268
|
+
- `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
|
|
269
|
+
- `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
|
|
270
|
+
|
|
271
|
+
`gate` is a reserved protocol shape for a future local representation of a
|
|
272
|
+
pending hub gate. Production code does not construct live hub gate events yet;
|
|
273
|
+
the local FIFO test and drill scope are recorded in
|
|
274
|
+
[`packages/work/test/shift-walkthrough.manual.md`](../packages/work/test/shift-walkthrough.manual.md).
|
|
275
|
+
|
|
276
|
+
If no daemon is listening, `next` exits `1` and prints the exact start guidance:
|
|
277
|
+
|
|
278
|
+
```text
|
|
279
|
+
no shift daemon at <stateDir>/shift.sock — start one with: owenloop shift start <crew…>
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Invalid arguments exit `2`. Other client or daemon runtime failures exit `1`.
|
|
283
|
+
All successful client output is one JSON object on stdout; diagnostics are on
|
|
284
|
+
stderr.
|
|
285
|
+
|
|
286
|
+
### `shift status [--state-dir <path>]`
|
|
287
|
+
|
|
288
|
+
```text
|
|
289
|
+
owenloop shift status [--state-dir <p>]
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
With a daemon, status exits `0` and prints:
|
|
293
|
+
|
|
294
|
+
```json
|
|
295
|
+
{ "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "attended_at": null, "started_at": 1738000000000 }
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
`attended_at` remains `null` until the first accepted `next` request. Without a
|
|
299
|
+
daemon, status is still a successful question: it exits `0` and prints
|
|
300
|
+
`{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
|
|
301
|
+
other client/runtime errors exit `1`.
|
|
302
|
+
|
|
303
|
+
### `shift end [--state-dir <path>]`
|
|
304
|
+
|
|
305
|
+
```text
|
|
306
|
+
owenloop shift end [--state-dir <p>]
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
An explicit end stops the loop, resolves an in-flight `next` with an `ended`
|
|
310
|
+
event, sends the final presence update with `attended_at` omitted so the hub
|
|
311
|
+
clears the attendance stamp, closes the socket, and prints
|
|
312
|
+
`{ "ok": true, "ended": true }` with exit `0`. Detached `exec` and `agent-run`
|
|
313
|
+
children remain alive to finish under their own leases. Signal shutdown (for
|
|
314
|
+
example, Ctrl-C) stops the daemon but does not synthesize the `ended` event or
|
|
315
|
+
perform the explicit attendance-clearing update.
|
|
316
|
+
|
|
317
|
+
If no daemon is listening, `end` exits `1` with the same start guidance as
|
|
318
|
+
`next`. Invalid arguments exit `2`; other client/runtime errors exit `1`.
|
|
319
|
+
|
|
320
|
+
## `work` — execution-side CLI companion
|
|
321
|
+
|
|
322
|
+
The execution-side commands ship in the same `owenloop` npm package and use the
|
|
323
|
+
same `owenloop` binary. Replace the old separate `owenwork` invocation directly:
|
|
324
|
+
|
|
325
|
+
```text
|
|
326
|
+
owenwork <subcommand> ... → owenloop work <subcommand> ...
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
The transplanted subcommand names remain. The standing Shift daemon is
|
|
330
|
+
only the root `owenloop shift` command; `owenloop work` has no standing-daemon alias.
|
|
331
|
+
`hold --mcp` remains because the machine-attached hold mount still exists.
|
|
332
|
+
Run `owenloop work --help` for the full role-specific usage.
|
|
333
|
+
|
|
334
|
+
The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
335
|
+
`XDG_CONFIG_HOME` is set to a non-blank value; otherwise it is
|
|
336
|
+
`$HOME/.config/owenloop/settings.json`.
|
|
337
|
+
|
|
338
|
+
| subcommand | what it does |
|
|
339
|
+
|---|---|
|
|
340
|
+
| `hold --order <id> [options]` | hold an order with a heartbeating lease |
|
|
341
|
+
| `exec <order-id> [options]` | run a command order in a self-leasing loop |
|
|
342
|
+
| `agent-run <order-id> [options]` | host an agent order's Step Agent in a harness and self-leasing loop |
|
|
343
|
+
| `prepare <workflow> [--origin <url>]` | fetch, cache, and normalize step specs |
|
|
344
|
+
| `lint <workflow-name \| path>` | lint `x.harness` option bags in a workflow definition |
|
|
345
|
+
| `sessions [--all] [--json]` | list recorded harness sessions and how to reopen them |
|
|
346
|
+
| `release --session <id> [options]` | drain a session's held claims |
|
|
347
|
+
| `settings` | print the resolved execution settings file |
|
|
348
|
+
| `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
|
|
349
|
+
|
|
350
|
+
### `work agent-run` — the only Step Agent dispatcher
|
|
351
|
+
|
|
352
|
+
`owenloop work agent-run` is the only supported way to dispatch an agent order.
|
|
353
|
+
The command resolves the verified local workflow definition, applies the final
|
|
354
|
+
`--harness` / environment / step harness selection, and checks every
|
|
355
|
+
`x.harness` restriction before cold start or resume. An unsupported restriction
|
|
356
|
+
starts no provider process, prints each exact refusal, releases the claim, and
|
|
357
|
+
exits `1`.
|
|
358
|
+
|
|
359
|
+
The Codex adapter refuses explicit `filesystem: read-only` and
|
|
360
|
+
`filesystem: workspace-write` before starting or resuming `codex app-server`.
|
|
361
|
+
The refusal is intentional: Codex configuration layers outside the thread
|
|
362
|
+
sandbox prevent the adapter from proving either neutral filesystem boundary.
|
|
363
|
+
Use the Claude Code adapter for the enforceable read-only/Owenloop-only policy,
|
|
364
|
+
or omit `filesystem` / declare `filesystem: unrestricted` only when the workflow
|
|
365
|
+
accepts the corresponding Codex behavior.
|
|
366
|
+
|
|
367
|
+
An absent `x.harness.tools` field preserves the adapter's default tool surface;
|
|
368
|
+
`tools: []` is an explicit empty allow-list. The two forms are not equivalent.
|
|
369
|
+
Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
|
|
370
|
+
`owenloop work lint` runs the same common and adapter checks, but runtime
|
|
371
|
+
preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
|
|
372
|
+
select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
|
|
373
|
+
for the capability matrix and the born-bound Owenloop control-plane exception.
|
|
374
|
+
|
|
375
|
+
**Harness-session durability.** `agent-run` records the provider session in the
|
|
376
|
+
machine-local `sessions.jsonl` log. The `active` row is a safety-critical gate:
|
|
377
|
+
the complete row and its trailing newline are written and fsynced before a
|
|
378
|
+
cold-start adapter may begin provider work or a resumed adapter may deliver new
|
|
379
|
+
feedback. Creating the log also fsyncs the containing directory where the
|
|
380
|
+
platform supports directory fsync. If the active append or fsync fails,
|
|
381
|
+
`agent-run` tears down the provider session, releases the order exactly once,
|
|
382
|
+
skips confirmation, writes no later lifecycle row, and exits with
|
|
383
|
+
`session-store-failed`. Later `turn-ended`, `submitted`, and `dead` rows keep
|
|
384
|
+
ordinary append durability; losing one causes conservative replay or retirement,
|
|
385
|
+
not unrecorded provider work. Compaction fsyncs the replacement before rename
|
|
386
|
+
and fsyncs the directory after rename so a successful compaction preserves a
|
|
387
|
+
previously durable active row.
|
|
388
|
+
|
|
389
|
+
## `trust` — local enrollment trust
|
|
390
|
+
|
|
391
|
+
The `trust` commands create the local enrollment root and signed enrollment
|
|
392
|
+
records. The commands are offline: they do not contact a hub or other remote
|
|
393
|
+
coordinator, and the remote side cannot create, sign, or endorse these records.
|
|
394
|
+
The org root is stored separately from `PrincipalKeyManager` at the injected
|
|
395
|
+
configuration root described in [Signing and key storage](crypto.md#enrollment-chains-attenuation-and-revocation).
|
|
396
|
+
|
|
397
|
+
```text
|
|
398
|
+
owenloop trust init [--force]
|
|
399
|
+
owenloop trust grant --key <pubkey-path> --principal <human|machine|agent>:<id> \
|
|
400
|
+
[--pools a,b|*] [--labels a,b|*] [--namespaces a,b|*] \
|
|
401
|
+
[--delegate no|<n>|unbounded] [--signing-key <path>] [--output <file>]
|
|
402
|
+
owenloop trust revoke --key <SHA256:…> --principal <kind>:<id> \
|
|
403
|
+
[--reason <text>] [--effective-from <epochMs>] \
|
|
404
|
+
[--signing-key <path>] [--output <file>]
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
- `trust init` generates an Ed25519 org-root key pair under the local config
|
|
408
|
+
directory. The containing directory is `0700`, the private key is `0600`,
|
|
409
|
+
and the public key is `0644`. Existing root files are refused unless
|
|
410
|
+
`--force` is supplied. The command prints paths and status, never private key
|
|
411
|
+
bytes.
|
|
412
|
+
- `trust grant` reads an Ed25519 public key from `--key`, assigns it to the
|
|
413
|
+
`--principal`, and signs an `EnrollmentGrantRecord`. Each scope axis defaults
|
|
414
|
+
to an empty array (deny by default); `--delegate` defaults to `no`. The
|
|
415
|
+
signing key defaults to the local org root unless `--signing-key` is given.
|
|
416
|
+
The signed DSSE envelope is written to `--output`, or to the local roster
|
|
417
|
+
directory using a SHA-256 hash of the enrolled key ID as its filename.
|
|
418
|
+
- `trust revoke` signs a `RevocationRecord` for the `SHA256:…` key in `--key`.
|
|
419
|
+
The signing key defaults to the local org root. Without `--effective-from`,
|
|
420
|
+
the cut starts at issuance. With an earlier `--effective-from`, the CLI
|
|
421
|
+
derives `backdated: true`; the flag is never accepted as an independent
|
|
422
|
+
boolean. The signed envelope is written to `--output`, or to the local
|
|
423
|
+
revocations directory using a SHA-256 hash of the revoked key ID.
|
|
424
|
+
|
|
425
|
+
These commands print one JSON result on success. They refuse malformed
|
|
426
|
+
principals, fingerprints, scope lists, delegation values, and timestamps before
|
|
427
|
+
performing the related filesystem or signing work. Trust records are only
|
|
428
|
+
local inputs to the chain validator; transporting a signed envelope is a
|
|
429
|
+
separate concern.
|
|
430
|
+
|
|
76
431
|
## `add` — installing shared workflow defs from GitHub
|
|
77
432
|
|
|
78
433
|
`owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
|
|
@@ -235,8 +590,8 @@ bounded — it only loads folders named by the fail-closed-validated
|
|
|
235
590
|
|
|
236
591
|
- **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
|
|
237
592
|
operator intent to target a literal dir and keeps the pure-scan behavior with
|
|
238
|
-
no fold-in — the rule is "was an override given",
|
|
239
|
-
`OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
|
|
593
|
+
no installed-def or CAS-store fold-in — the rule is "was an override given",
|
|
594
|
+
so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
|
|
240
595
|
Pointing `--defs` straight at an install folder
|
|
241
596
|
(`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
|
|
242
597
|
- **Precedence.** Project-local (top-level) defs win over installed defs; among
|
|
@@ -256,13 +611,13 @@ ref) surfaces as a 404 from the sha-resolve step.
|
|
|
256
611
|
**Trust model — what `add` does and does not protect.** Installing a package
|
|
257
612
|
executes nothing at install time: `add` only fetches, validates, and writes
|
|
258
613
|
YAML under the defs dir. But an installed def's steps *run* later, with
|
|
259
|
-
whatever privileges the host process and its dispatcher grant their
|
|
260
|
-
owenloop itself never executes a step body — `
|
|
261
|
-
|
|
614
|
+
whatever privileges the host process and its dispatcher grant their Step Agents.
|
|
615
|
+
owenloop itself never executes a step body — `executor:`/`command:` are opaque
|
|
616
|
+
fields it carries through untouched and never shells out (see [What owenloop is
|
|
262
617
|
not](../README.md#what-owenloop-is-not) and
|
|
263
|
-
[`docs/authoring.md`](authoring.md#
|
|
264
|
-
real risk surface is the
|
|
265
|
-
prompts and `command:` strings that ship in a package are handed to
|
|
618
|
+
[`docs/authoring.md`](authoring.md#executor--declaring-the-executor)) — so the
|
|
619
|
+
real risk surface is the Shift or Step Agent you point at these defs: the
|
|
620
|
+
prompts and `command:` strings that ship in a package are handed to Step Agents that
|
|
266
621
|
typically run with your full local privileges. **Install only sources you
|
|
267
622
|
trust.**
|
|
268
623
|
|
|
@@ -280,7 +635,7 @@ install *step* — staged all-or-nothing validation with an atomic swap, path
|
|
|
280
635
|
containment (including symlink-aware `bodyFile` checks), and archive resource
|
|
281
636
|
bounds — not the def *content* that later executes. `add` validates a def's
|
|
282
637
|
structure and contains its paths; it does not sandbox or sanitize what a step
|
|
283
|
-
body will do once a
|
|
638
|
+
body will do once a Step Agent runs it. That trust decision stays yours.
|
|
284
639
|
|
|
285
640
|
**Untrusted-archive safety.** `add` treats the fetched repo as untrusted and
|
|
286
641
|
refuses the whole install (nothing written) on any of these:
|
|
@@ -301,14 +656,501 @@ refuses the whole install (nothing written) on any of these:
|
|
|
301
656
|
buffered into memory (the extraction limits above still re-check the size once
|
|
302
657
|
the bytes are in hand).
|
|
303
658
|
- **Request timeouts.** The sha-resolve fetch times out after 30s and the
|
|
304
|
-
tarball download after 5 min, each surfacing as a friendly error.
|
|
659
|
+
tarball download after 5 min, each surfacing as a friendly error. The
|
|
660
|
+
bundle route applies the same 256 MiB cap and 5 min timeout to its file
|
|
661
|
+
read and URL fetch (see the next section).
|
|
662
|
+
|
|
663
|
+
## `add` with bundles — the content-addressed workflow store
|
|
664
|
+
|
|
665
|
+
`owenloop add <owner>/<repo>[@ref]` (the previous section) installs
|
|
666
|
+
GitHub repos by name into `<defsDir>/<owner>-<repo>-<hash>/`. The **bundle**
|
|
667
|
+
route is a separate, content-addressed installation path for `.wnlp` workflow
|
|
668
|
+
bundles:
|
|
669
|
+
|
|
670
|
+
```text
|
|
671
|
+
owenloop add widget.wnlp # install into the PROJECT store
|
|
672
|
+
owenloop add ./packs/widget.wnlp --global # install into the GLOBAL store
|
|
673
|
+
owenloop add https://example.com/widget.wnlp
|
|
674
|
+
owenloop add --recover [--global] # offline crash recovery (per root)
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
The source is classified before anything else: `owner/repo[@ref]` keeps the
|
|
678
|
+
GitHub route byte-for-byte unchanged; a path ending in `.wnlp` is a bundle
|
|
679
|
+
file; an `http:`/`https:` URL is a bundle URL. Any other URL scheme
|
|
680
|
+
(`ftp:`, `file:`, …) is refused — never a silent fallback. `--global` applies
|
|
681
|
+
only to `.wnlp` bundle sources; a GitHub source with `--global` is refused
|
|
682
|
+
before any network request. The source string is origin data only (diagnostics
|
|
683
|
+
and messages); it is never joined into a filesystem path and never part of a
|
|
684
|
+
bundle's identity. Identity comes from the bundle's own
|
|
685
|
+
`namespace/name@version` coordinate and its canonical content digest.
|
|
686
|
+
|
|
687
|
+
**The `.wnlp` route requires two adapters and fails closed without them.**
|
|
688
|
+
Bundle ingestion (unpacking, manifest integrity, canonical digest,
|
|
689
|
+
coordinate) and pre-commit verification are separate modules with no
|
|
690
|
+
permissive fallback: with either adapter missing, `add` refuses with a named
|
|
691
|
+
error before any staging, journal, or index write. The default CLI binds both
|
|
692
|
+
production adapters. The pre-commit verifier consumes the publication sidecars
|
|
693
|
+
written by `publish` and applies the local `defPolicy` before the object or index
|
|
694
|
+
commit. Hosts that provide both adapters can install real `.wnlp` output from
|
|
695
|
+
`packBundle`; use the `publish` command to create the `.wnlp` bundle plus a
|
|
696
|
+
signed or explicitly unsigned sidecar.
|
|
697
|
+
|
|
698
|
+
### Definition publication policy
|
|
699
|
+
|
|
700
|
+
`defPolicy` is the local execution and installation policy for workflow
|
|
701
|
+
publication signatures. The settings file is
|
|
702
|
+
`$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is non-blank,
|
|
703
|
+
otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
|
|
704
|
+
settings file, write a JSON object such as:
|
|
705
|
+
|
|
706
|
+
```json
|
|
707
|
+
{
|
|
708
|
+
"defPolicy": "enforce"
|
|
709
|
+
}
|
|
710
|
+
```
|
|
711
|
+
|
|
712
|
+
For a one-off CLI invocation, set `OWENLOOP_DEF_POLICY` in the environment, for
|
|
713
|
+
example `OWENLOOP_DEF_POLICY=enforce owenloop add widget.wnlp`. The local
|
|
714
|
+
precedence is explicit host-provided policy, then `OWENLOOP_DEF_POLICY`, then
|
|
715
|
+
the settings file, then the built-in default `warn`. An invalid environment or
|
|
716
|
+
settings-file value fails loudly; it never degrades to `off`.
|
|
717
|
+
|
|
718
|
+
When a host supplies an already-verified organization policy floor through the
|
|
719
|
+
`policyFloor` option seam, the floor is applied **after** that local precedence.
|
|
720
|
+
`unsignedDefs: warn` raises the minimum to `warn`; `unsignedDefs: refuse` raises
|
|
721
|
+
the minimum to `enforce`; the effective policy is the stricter of local policy
|
|
722
|
+
and the floor. **Therefore, local `off` no longer means “no enforcement” when a
|
|
723
|
+
verified org floor is present.** A local operator cannot use `off` to opt out of
|
|
724
|
+
a verified floor. A missing, malformed, unsigned, wrongly signed, or
|
|
725
|
+
under-scoped floor leaves the local policy unchanged.
|
|
726
|
+
|
|
727
|
+
The current CLI and production configuration do not load or verify a floor.
|
|
728
|
+
`policyFloor` is an injection seam only, so this feature is inert until a host
|
|
729
|
+
wires floor loading and verification into that seam.
|
|
730
|
+
|
|
731
|
+
The policy applies at install time and again at execution time. The following
|
|
732
|
+
table describes the local policy result before any verified floor is applied.
|
|
733
|
+
The table uses these verdicts:
|
|
734
|
+
|
|
735
|
+
- `verified` — the publication sidecar verifies against the bundle digest and a
|
|
736
|
+
signer in the local trust root.
|
|
737
|
+
- `unsigned` — the bundle has no publication signature (including an explicit
|
|
738
|
+
`.wnlp.unsigned` sidecar).
|
|
739
|
+
- `unverifiable` — verification could not be completed, such as when the trust
|
|
740
|
+
root is missing or malformed.
|
|
741
|
+
- `invalid` — a present publication signature fails verification, including a
|
|
742
|
+
digest or signer mismatch.
|
|
743
|
+
|
|
744
|
+
| publication verdict | `enforce` | `warn` | `off` |
|
|
745
|
+
|---|---|---|---|
|
|
746
|
+
| `verified` | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. |
|
|
747
|
+
| `unsigned` or `unverifiable` | Install refuses; agent and command execution refuse. | Install warns to stderr and succeeds; agent execution warns and proceeds; command execution refuses. | Install succeeds silently; agent execution proceeds silently; command execution refuses. |
|
|
748
|
+
| `invalid` | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. |
|
|
749
|
+
|
|
750
|
+
**Command-worker hard rule.** A `worker: command` order requires full
|
|
751
|
+
enforcement in every policy value, including `off`: the definition must be
|
|
752
|
+
verified, the enrollment chain must be verified, and the signer scope must be
|
|
753
|
+
checked. `off` does not disable command-worker enforcement. `warn` and `off`
|
|
754
|
+
never allow an unsigned, unverifiable, or invalid definition to reach the
|
|
755
|
+
shell. The command check runs before the policy value is read, and a refusal
|
|
756
|
+
uses the normal `InstructionRefusal` path so the lease stops before command
|
|
757
|
+
execution. A policy floor cannot relax this gate; the gate also fails closed
|
|
758
|
+
regardless of any floor. If an execution host has no publication verifier
|
|
759
|
+
configured, the definition is `unverifiable`; command workers therefore refuse
|
|
760
|
+
rather than treating installed bytes as published trust.
|
|
761
|
+
|
|
762
|
+
### Consume-side artifact policy
|
|
763
|
+
|
|
764
|
+
`artifactPolicy` controls how agent and MCP drivers handle absent evidence and
|
|
765
|
+
missing local prerequisites for signed dynamic artifact values. Supplied but
|
|
766
|
+
invalid evidence always refuses; the policy is a scalar with the same values as
|
|
767
|
+
`defPolicy`: `enforce`, `warn`, or `off`. The precedence is explicit host
|
|
768
|
+
option, then `OWENLOOP_ARTIFACT_POLICY`, then the `artifactPolicy` key in the
|
|
769
|
+
execution settings file, then the built-in default `warn`.
|
|
770
|
+
|
|
771
|
+
For example, the settings file can contain:
|
|
772
|
+
|
|
773
|
+
```json
|
|
774
|
+
{
|
|
775
|
+
"artifactPolicy": "enforce"
|
|
776
|
+
}
|
|
777
|
+
```
|
|
305
778
|
|
|
306
|
-
|
|
779
|
+
A one-off invocation can set
|
|
780
|
+
`OWENLOOP_ARTIFACT_POLICY=enforce owenloop work agent-run <order-id>`.
|
|
781
|
+
Invalid values fail loudly; an invalid value never becomes `off`.
|
|
782
|
+
|
|
783
|
+
The consuming driver verifies each delivered value against its serialized DSSE
|
|
784
|
+
submission proof, the signed value digest and version, the locally anchored
|
|
785
|
+
producer enrollment chain, revocations, and any supplied consuming demand's
|
|
786
|
+
scope. A missing proof is not the same as invalid evidence. Dynamic values and
|
|
787
|
+
rejection reasons remain on the wire; the driver verifies those values and
|
|
788
|
+
refuses the whole order on failure rather than dropping only one path.
|
|
789
|
+
|
|
790
|
+
A valid historical proof is not enough to establish the version claimed for the
|
|
791
|
+
current delivery. Ordinary consumed artifacts bind the signed version to the
|
|
792
|
+
claim-time version in `consumedFingerprint`; owed rejection reasons bind to the
|
|
793
|
+
owed claim-time version. If that authoritative expected version is absent, the
|
|
794
|
+
verdict is `unverifiable`, never `verified`, even when the signature, value
|
|
795
|
+
digest, and enrollment chain all verify. The policy table therefore applies
|
|
796
|
+
without a hidden exception: `enforce` refuses that artifact, `warn` warns and
|
|
797
|
+
admits it, and `off` admits it without calling the proof verified. The
|
|
798
|
+
command-worker hard rule below still refuses it under every policy.
|
|
799
|
+
|
|
800
|
+
The current production `exec`, `agent-run`, and `hold` roles do not supply a
|
|
801
|
+
pool, label, or namespace demand. `OrderPacket` has no such demand field to
|
|
802
|
+
derive, so production consume gates enforce the enrollment chain, attenuation,
|
|
803
|
+
and revocation checks but do not apply a demand-dependent `scopePermits`
|
|
804
|
+
restriction. A caller that supplies a demand through the verifier seam gets the
|
|
805
|
+
full scope check. This limitation is a named follow-up.
|
|
806
|
+
|
|
807
|
+
| consumed-evidence verdict | `artifactPolicy=enforce` | `artifactPolicy=warn` | `artifactPolicy=off` |
|
|
808
|
+
|---|---|---|---|
|
|
809
|
+
| `verified` | admit | admit | admit |
|
|
810
|
+
| `absent` | refuse | warn and admit | admit |
|
|
811
|
+
| `unverifiable` | refuse | warn and admit | admit |
|
|
812
|
+
| `invalid` | refuse | refuse | refuse |
|
|
813
|
+
|
|
814
|
+
A refusal is an actionable integrity event. The refusal names the failed link
|
|
815
|
+
and artifact, using names such as `no-proof`, `signature`, `value-digest`,
|
|
816
|
+
`version`, `chain`, `scope`, or `prerequisite`, and includes the workflow, run,
|
|
817
|
+
and step. The driver refuses the whole order; operators must not suppress the
|
|
818
|
+
message or continue with a manually stripped packet.
|
|
819
|
+
|
|
820
|
+
The policy floor's `unsignedArtifacts: warn` value raises the local minimum to
|
|
821
|
+
`artifactPolicy=warn`; `unsignedArtifacts: refuse` raises it to `enforce`. A
|
|
822
|
+
verified floor is merged after local precedence, so local `off` cannot weaken
|
|
823
|
+
the floor.
|
|
824
|
+
|
|
825
|
+
**Command-worker hard rule.** A `worker: command` order refuses `absent`,
|
|
826
|
+
`unverifiable`, and `invalid` consumed evidence regardless of `artifactPolicy`,
|
|
827
|
+
including `off`. The consume-side gate runs before origin or artifact policy
|
|
828
|
+
lookup and before a shell command is built or passed to `/bin/sh -c`. A command
|
|
829
|
+
worker must have a configured consume-side verifier; an unverified dynamic value
|
|
830
|
+
must never reach the shell. Agent prompt rendering and MCP `get_order` likewise
|
|
831
|
+
fail closed when dynamic data exists but no verifier is configured. The driver
|
|
832
|
+
samples the consumer's injected clock once per complete gate invocation; a
|
|
833
|
+
revocation effective at `effectiveFrom <= at` makes a previously consumable
|
|
834
|
+
artifact unconsumable on a later invocation.
|
|
835
|
+
|
|
836
|
+
### Definition origin policy
|
|
837
|
+
|
|
838
|
+
`originRules` is a separate namespace-scoped provenance policy. A signed file
|
|
839
|
+
publication may include `<bundle>.origin.dsse`; installation verifies that
|
|
840
|
+
sidecar against the local `allowed_signers` root and retains the exact bytes at
|
|
841
|
+
`<store-root>/.owenloop/origins/<digest>.dsse`. Execution re-verifies the
|
|
842
|
+
retained evidence against the current trust root. Only a `verified` origin
|
|
843
|
+
verdict is retained. A bundle carrying only `<bundle>.origin.dsse` — with
|
|
844
|
+
neither a publication `.dsse` nor an unsigned marker — is refused at install for
|
|
845
|
+
every origin-policy value, including `off`. `publish` never emits that shape;
|
|
846
|
+
`--unsigned` removes both sidecars. A hub or other remote coordinator may relay
|
|
847
|
+
the sidecar, but never authors or supplies the origin rule.
|
|
848
|
+
|
|
849
|
+
The origin mode uses the same policy values as `defPolicy` — `enforce`, `warn`,
|
|
850
|
+
and `off` — and follows the same scalar precedence: explicit host option,
|
|
851
|
+
`OWENLOOP_ORIGIN_POLICY`, settings-file `originPolicy`, then `warn`. These are
|
|
852
|
+
not trust modes: `Seamless`, `Strict`, and `Paranoid` are a separate axis;
|
|
853
|
+
`Seamless` maps to `warn`, `Strict` maps to `enforce`, and `off` is a local
|
|
854
|
+
operator escape hatch with no trust-mode equivalent. The rule map has no
|
|
855
|
+
environment-variable spelling: explicit host `originRules`, then settings-file
|
|
856
|
+
`originRules`, then an empty map. A namespace with no matching rule has no origin
|
|
857
|
+
requirement. A malformed rule map is a named settings error, not an empty-policy
|
|
858
|
+
fallback.
|
|
859
|
+
|
|
860
|
+
Rules accept exact namespaces (`prod`), namespace prefixes (`prod*`), and
|
|
861
|
+
trailing `/*` sugar (`prod/*`, equivalent to `prod`). `*` and `*/*` are
|
|
862
|
+
catch-all rules. Exact matches beat prefixes; the longest prefix wins; keys
|
|
863
|
+
that normalize to equal specificity, such as `prod` and `prod/*`, are rejected.
|
|
864
|
+
Rule values are minimum provenance strengths, ordered `git` > `console` >
|
|
865
|
+
`agent`; therefore a `console` rule accepts verified `git` and `console`
|
|
866
|
+
origins, and an `agent` rule accepts all three. `any` imposes no requirement.
|
|
867
|
+
|
|
868
|
+
Origin verdicts remain distinct:
|
|
869
|
+
|
|
870
|
+
- `verified` has a strength and is checked against the selected minimum.
|
|
871
|
+
- `absent` means no origin bytes are available. For a signed file publication,
|
|
872
|
+
this means no sidecar was recorded. Unsigned publications and non-file install
|
|
873
|
+
sources also produce `absent`, but those definitions structurally cannot carry
|
|
874
|
+
an origin; those cases must not be described as “no origin was recorded.”
|
|
875
|
+
- `unverifiable` means a prerequisite such as the trust root is unavailable.
|
|
876
|
+
- `invalid` means present origin evidence failed verification and is refused at
|
|
877
|
+
every origin mode, including `off`.
|
|
878
|
+
|
|
879
|
+
For a matched rule, the local origin mode behaves as follows:
|
|
880
|
+
|
|
881
|
+
| origin verdict | `originPolicy=enforce` | `originPolicy=warn` | `originPolicy=off` |
|
|
882
|
+
|---|---|---|---|
|
|
883
|
+
| `verified` meeting the minimum | Install and execution succeed. | Install and execution succeed. | Install and execution succeed. |
|
|
884
|
+
| `verified` weaker than the minimum | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
|
|
885
|
+
| `absent` or `unverifiable` | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
|
|
886
|
+
| `invalid` | Install refuses; execution refuses. | Install refuses; execution refuses. | Install refuses; execution refuses. |
|
|
887
|
+
|
|
888
|
+
The table applies only when a rule matches. During execution, the driver
|
|
889
|
+
recovers the namespace by reverse-scanning project and global store indexes for
|
|
890
|
+
the bundle digest. Equivalent requirements deduplicate. Different requirements
|
|
891
|
+
produce a named ambiguity refusal. If no coordinate is indexed, `enforce`
|
|
892
|
+
refuses, `warn` warns, and `off` proceeds. With an empty `originRules` map, the
|
|
893
|
+
default resolver still invokes the origin verifier once per order, but skips the
|
|
894
|
+
expensive index reverse-scan; invalid retained origin evidence still refuses.
|
|
895
|
+
|
|
896
|
+
A verified policy floor maps `originRules: advisory` to minimum
|
|
897
|
+
`originPolicy=warn` and `originRules: enforced` to minimum
|
|
898
|
+
`originPolicy=enforce`. The origin floor is parallel to the publication floor;
|
|
899
|
+
it does not alter `defPolicy`.
|
|
900
|
+
|
|
901
|
+
**Origin policy never relaxes the command-worker hard rule.** A
|
|
902
|
+
`worker: command` order must pass the publication verification gate first, even
|
|
903
|
+
when `defPolicy=off`, and only then runs the origin check. Unsigned,
|
|
904
|
+
unverifiable, or invalid publication evidence never reaches the shell. An
|
|
905
|
+
origin mode of `off` and every policy-floor preset leave that gate unchanged.
|
|
906
|
+
|
|
907
|
+
The local SSHSIG trust root is
|
|
908
|
+
`$XDG_CONFIG_HOME/owenloop/allowed_signers`, or
|
|
909
|
+
`$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
|
|
910
|
+
missing or malformed trust root is `unverifiable`, not `unsigned`.
|
|
911
|
+
|
|
912
|
+
### The two store roots
|
|
913
|
+
|
|
914
|
+
A store root holds exactly this layout:
|
|
915
|
+
|
|
916
|
+
```text
|
|
917
|
+
<root>/
|
|
918
|
+
index.json # coordinate → {digest, pinned, workflows?} index
|
|
919
|
+
objects/
|
|
920
|
+
sha256/
|
|
921
|
+
<64-hex-content-digest>/ # one immutable object per digest
|
|
922
|
+
… # the bundle's files
|
|
923
|
+
.owenloop/ # per-root lock + crash journal
|
|
924
|
+
add.lock
|
|
925
|
+
add.journal
|
|
926
|
+
.owenloop-staging/ # transient staging (cleared on exit)
|
|
927
|
+
```
|
|
928
|
+
|
|
929
|
+
- **Project store root** = the resolved defs directory itself (`--defs`,
|
|
930
|
+
`OWENLOOP_DEFS`, or `./workflows`). The project's pins are reviewable in
|
|
931
|
+
git there, and the nested `objects/sha256/<digest>/` layout stays below
|
|
932
|
+
the def loader's scan depth.
|
|
933
|
+
- **Global store root** = `<home>/.owenloop/workflows`. `--global` selects it;
|
|
934
|
+
it cannot be combined with `--defs` (the global store has a fixed
|
|
935
|
+
home-directory location, so an override would only create ambiguity —
|
|
936
|
+
refused with a clear message). The global root is never used by the
|
|
937
|
+
GitHub route.
|
|
938
|
+
|
|
939
|
+
**Injected home requirement.** `<home>` is the first non-blank value from the
|
|
940
|
+
caller-injected `HOME` and `USERPROFILE` environment variables (`HOME` wins).
|
|
941
|
+
The `.wnlp` bundle route uses the same injected home for its default external
|
|
942
|
+
recovery-marker directory, `<home>/.owenloop/recovery-markers`, even when the
|
|
943
|
+
bundle targets the project store. If neither variable is supplied, bundle
|
|
944
|
+
installation refuses before any object or index commit; it never falls back to
|
|
945
|
+
the process user's ambient home. `add --recover --global` has the same
|
|
946
|
+
requirement. Project recovery of a v2 fresh-install journal also refuses when
|
|
947
|
+
its recovery marker requires a home and neither variable is supplied.
|
|
948
|
+
|
|
949
|
+
Every object path derives ONLY from its validated digest (lowercase 64-hex).
|
|
950
|
+
Coordinates, source strings, and version text never join into a path.
|
|
951
|
+
|
|
952
|
+
### What an install does, in order
|
|
953
|
+
|
|
954
|
+
1. Read the bundle bytes (file or URL) *before* taking the lock — a slow
|
|
955
|
+
download never holds the project lock. A local `.wnlp` must be a bounded
|
|
956
|
+
regular file: missing, symlinked, non-regular, or over the 256 MiB cap
|
|
957
|
+
(checked before *and* after the read) is refused naming the path as
|
|
958
|
+
given. A URL fetch uses the same 5 min timeout, refuses redirects
|
|
959
|
+
(`redirect: 'error'`) instead of following them silently, and streams
|
|
960
|
+
through the same bounded reader.
|
|
961
|
+
2. Acquire the canonical root lock at `<root>/.owenloop/add.lock`. A GitHub
|
|
962
|
+
install also retains its legacy cwd-derived lock for compatibility and, when
|
|
963
|
+
the resolved `--defs` root differs from that cwd, acquires both locks in a
|
|
964
|
+
fixed order. The canonical lock makes bundle installs from different cwd
|
|
965
|
+
values serialize when they target one shared `--defs` root; the additional
|
|
966
|
+
GitHub lock keeps the legacy route compatible.
|
|
967
|
+
3. Recover a prior interrupted install (before clearing staging — the
|
|
968
|
+
backups a rollback needs live under the staging root).
|
|
969
|
+
4. Reread and validate the index **inside** the lock (a corrupt index is a
|
|
970
|
+
hard error, never a silent reset).
|
|
971
|
+
5. Ingest via the bundle adapter: unpack into staging, check manifest
|
|
972
|
+
integrity and runtime compatibility, compute the canonical digest, and
|
|
973
|
+
extract the full coordinate. The runtime check uses Owenloop's production
|
|
974
|
+
package version and advertised feature set. A tampered, malformed, or
|
|
975
|
+
runtime-incompatible bundle stops here — staging debris only, nothing
|
|
976
|
+
committed.
|
|
977
|
+
6. Validate the staged tree with the engine's strict pass — the exact bytes
|
|
978
|
+
that will be committed (parse/lint/validate/bounded `check` + the strict
|
|
979
|
+
cross-def backstop). For a real `.wnlp`, validation parses `bundle.yaml`
|
|
980
|
+
through the same runtime-admission boundary and loads every workflow path
|
|
981
|
+
listed in its `workflows` map; the package manifest itself is not treated as
|
|
982
|
+
a workflow definition. Any problem refuses the whole install and prints
|
|
983
|
+
every reason.
|
|
984
|
+
7. Run the pre-commit verifier (after content validation, before any swap or
|
|
985
|
+
index write). A rejection commits nothing.
|
|
986
|
+
8. Write the `applying` crash journal (v2 — its commit-point evidence is the
|
|
987
|
+
hash of the post-install index bytes).
|
|
988
|
+
9. Atomically swap the staged object into `objects/sha256/<digest>`
|
|
989
|
+
(retaining any displaced content on the commit handle), then harden it
|
|
990
|
+
in place: canonical `0644` files become read-only `0444`, canonical `0755`
|
|
991
|
+
files become read/execute-only `0555`, and directories become non-writable
|
|
992
|
+
`0555`. Hardening preserves the executable distinction needed for canonical
|
|
993
|
+
object reconstruction. Hardening is defense in depth, not the integrity proof
|
|
994
|
+
— verification reconstructs the complete canonical tar, including
|
|
995
|
+
`bundle.yaml`, and matches its SHA-256 digest to the object path. A hardening
|
|
996
|
+
failure rolls the swap back; a partially hardened object is never committed.
|
|
997
|
+
If the digest's object already exists, the install verifies the existing
|
|
998
|
+
object through the ingest adapter and commits an index-only change instead
|
|
999
|
+
(dedupe) — a corrupt or runtime-incompatible existing object is a hard
|
|
1000
|
+
integrity error, never replaced and never fallen through.
|
|
1001
|
+
10. Atomically write `index.json` — the **durable commit point**. Past here
|
|
1002
|
+
a crash rolls forward; before it, everything rolls back. An index-write
|
|
1003
|
+
failure rolls the directory state back and leaves the previous object
|
|
1004
|
+
and index exactly as they were.
|
|
1005
|
+
11. Advance the journal to `finalizing`, discard the retained backup and
|
|
1006
|
+
staging, remove the journal, release the lock.
|
|
1007
|
+
|
|
1008
|
+
On success `add` prints the structured result:
|
|
1009
|
+
|
|
1010
|
+
```jsonc
|
|
1011
|
+
{
|
|
1012
|
+
"ok": true,
|
|
1013
|
+
"source": "widget.wnlp", // or the URL
|
|
1014
|
+
"level": "project", // or "global"
|
|
1015
|
+
"coordinate": "acme/widget@1.0.0",
|
|
1016
|
+
"digest": "<64-hex>",
|
|
1017
|
+
"workflows": ["delivery", "init"], // every workflow name in the bundle, sorted
|
|
1018
|
+
"objectPath": "<root>/objects/sha256/<64-hex>",
|
|
1019
|
+
"installed": true // false when deduplicated
|
|
1020
|
+
}
|
|
1021
|
+
```
|
|
307
1022
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
`
|
|
1023
|
+
**Conflict and re-install.** An existing coordinate at a DIFFERENT digest is
|
|
1024
|
+
a conflict error — no implicit retarget; the original digest is retained and
|
|
1025
|
+
nothing is written. An existing coordinate at the SAME digest deduplicates
|
|
1026
|
+
(`installed: false`), verifying the existing object before trusting it.
|
|
1027
|
+
|
|
1028
|
+
**Crash recovery** is the same two-phase discipline as the GitHub route,
|
|
1029
|
+
generalized: the v2 journal's commit-point test compares the hash of the
|
|
1030
|
+
current `index.json` bytes against the journal's recorded metadata hash
|
|
1031
|
+
(route-neutral — no GitHub ledger involved). A fresh v2 install also writes a
|
|
1032
|
+
single-use external recovery marker under the user's recovery-marker directory
|
|
1033
|
+
(default `<home>/.owenloop/recovery-markers`, derived from the injected home
|
|
1034
|
+
described above) before the applying journal. If a crash leaves the destination
|
|
1035
|
+
present with no staging or backup, recovery
|
|
1036
|
+
discards that destination only when the marker exactly matches the store root,
|
|
1037
|
+
destination segments, staging id, and `hadDest: false`; a missing or mismatched
|
|
1038
|
+
marker refuses and preserves the destination and journal. `add --recover --global`
|
|
1039
|
+
runs the store's recovery standalone against the global root with no network
|
|
1040
|
+
and prints `{"ok":true,"recovered":false|true,"outcome":…}` exactly
|
|
1041
|
+
like the project variant. A v1 (GitHub-schema) journal found at the global root
|
|
1042
|
+
is refused fail-closed — there is no ledger there to vouch for it — and a
|
|
1043
|
+
journal recorded against a *different* store root is refused rather than
|
|
1044
|
+
trusting its absolute path. Refusals leave the journal in place as evidence.
|
|
1045
|
+
|
|
1046
|
+
### Resolving what is installed — two separate APIs
|
|
1047
|
+
|
|
1048
|
+
Resolution is deliberately split so execution code cannot accidentally call
|
|
1049
|
+
human-name resolution. Both are library APIs (exported from the package
|
|
1050
|
+
root); every successful resolution verifies the object through the ingest
|
|
1051
|
+
adapter before returning a path — permissions and object shape on disk are
|
|
1052
|
+
defense in depth, not an integrity proof.
|
|
1053
|
+
|
|
1054
|
+
- **Digest resolution (execution).** `resolveWorkflowDigest({digest,
|
|
1055
|
+
projectRoot?, globalRoot, verifier})` — digest only; no index and no
|
|
1056
|
+
workflow name participate. The project object path is tested first when a
|
|
1057
|
+
project root exists; an ABSENT project object may fall through to global,
|
|
1058
|
+
but a PRESENT project object that fails its type probe or verification is
|
|
1059
|
+
a hard integrity error — project tampering is never hidden by falling back
|
|
1060
|
+
to a valid global copy. When both levels hold the same digest, ONE result
|
|
1061
|
+
comes back (level `project`, with presence metadata), not two candidates.
|
|
1062
|
+
Absent at both levels ⇒ `object-missing` integrity error.
|
|
1063
|
+
- **Coordinate resolution (human/CLI).** `resolveWorkflowCoordinate({coordinate,
|
|
1064
|
+
projectRoot?, globalRoot, verifier})` reads BOTH indexes, fail-closed (a
|
|
1065
|
+
corrupt index is a hard error, never silently empty). No entry at either
|
|
1066
|
+
level ⇒ a structured **not-found** error. A project entry wins whenever it
|
|
1067
|
+
exists, even when the global index maps the same coordinate to a different
|
|
1068
|
+
digest; global is the fallback only when project has no match. An index entry
|
|
1069
|
+
whose selected object is missing or corrupt is an integrity error, never a
|
|
1070
|
+
returned path.
|
|
1071
|
+
|
|
1072
|
+
**Calls resolution for installed bundle workflows.** In the default CLI context
|
|
1073
|
+
(no explicit `--defs`/`OWENLOOP_DEFS`), `defs`/`create`/`tick` load CAS workflows
|
|
1074
|
+
from the project and global bundle-store indexes in addition to filesystem defs
|
|
1075
|
+
and the GitHub `add` ledger. A CAS workflow is addressable by the qualified
|
|
1076
|
+
`<package>/<workflow>` name, so a project-local or `add`-installed workflow can
|
|
1077
|
+
call it explicitly. A bare call from a CAS-loaded workflow resolves a sibling
|
|
1078
|
+
from the same bundle digest first; if no sibling has that name, ordinary flat
|
|
1079
|
+
lookup remains available. Bare CAS names are not registered globally, so a
|
|
1080
|
+
workflow in bundle A cannot accidentally call a same-named workflow from bundle
|
|
1081
|
+
B.
|
|
1082
|
+
|
|
1083
|
+
The precedence is explicit: project-local definitions win first, then
|
|
1084
|
+
GitHub-`add` installed definitions, then CAS definitions under qualified keys.
|
|
1085
|
+
Within the CAS layer, exactly one installed bundle holds the unqualified
|
|
1086
|
+
`<package>/<workflow>` name, chosen by two rules in order and never by install
|
|
1087
|
+
order:
|
|
1088
|
+
|
|
1089
|
+
1. **Level.** If any candidate is named by the *project* index, only project
|
|
1090
|
+
candidates compete. A project pin of `pkg@0.1.0` therefore beats a global
|
|
1091
|
+
install of `pkg@0.9.9`. This holds even when the project's own object bytes
|
|
1092
|
+
are missing and were served by exact-digest fallback from the global store —
|
|
1093
|
+
the index that names the object decides, not where the bytes were read.
|
|
1094
|
+
2. **Version.** Among the survivors, the highest canonical SemVer precedence
|
|
1095
|
+
wins (SemVer §11, so `0.1.10` beats `0.1.2` and `1.0.0` beats `1.0.0-rc.1`).
|
|
1096
|
+
|
|
1097
|
+
A canonical SemVer version never loses to a non-SemVer one. If two or more
|
|
1098
|
+
candidates compete and *none* carries a canonical SemVer version, the selection
|
|
1099
|
+
**fails closed**: the unqualified name is left unregistered and a warning names
|
|
1100
|
+
the versions involved, because there is no defined precedence to pick by. Call an
|
|
1101
|
+
exact `<namespace>/<name>@<version>` coordinate in that case. A single
|
|
1102
|
+
non-SemVer version still holds its name — there is nothing to order.
|
|
1103
|
+
|
|
1104
|
+
The refusal warning names only the versions that actually competed. A version
|
|
1105
|
+
dropped by rule 1 is reported separately as never having competed, since it lost
|
|
1106
|
+
on level and was never judged on its version at all. For the same reason,
|
|
1107
|
+
precedence warnings say `project-indexed` / `global-indexed`: precedence follows
|
|
1108
|
+
the index that named the object, whereas a registration's reported level is the
|
|
1109
|
+
store its verified bytes came from, and the two differ under exact-digest
|
|
1110
|
+
fallback.
|
|
1111
|
+
|
|
1112
|
+
Every version that did not win remains reachable under its digest-scoped key, so
|
|
1113
|
+
an already-pinned execution cannot be retargeted, and every exact
|
|
1114
|
+
`<namespace>/<name>@<version>` coordinate always resolves to its own object
|
|
1115
|
+
regardless of which version currently holds the unqualified name.
|
|
1116
|
+
A corrupt CAS index, object, or workflow is skipped with a warning during
|
|
1117
|
+
read-side discovery, so it does not make `status` fail. A running workflow keeps
|
|
1118
|
+
the definition snapshot from its creation (§28), including the CAS bundle
|
|
1119
|
+
provenance used for sibling lookup; installing a newer bundle therefore does not
|
|
1120
|
+
retarget an existing parent instance. The bundle spawn-time pin check compares
|
|
1121
|
+
canonical bundle digests and records a rejected `calls:` debt instead of running
|
|
1122
|
+
a mismatched child.
|
|
1123
|
+
|
|
1124
|
+
Store roots and object directories are probed with `lstat`, never `stat`:
|
|
1125
|
+
a symlink or non-directory squatting at a root, an index path, or an object
|
|
1126
|
+
path is refused outright, and reads never follow a link outside the
|
|
1127
|
+
intended tree.
|
|
1128
|
+
|
|
1129
|
+
**GitHub-route compatibility.** The bundle route changes nothing about
|
|
1130
|
+
`add <owner>/<repo>[@ref]`: the same inputs reach the same parser, the
|
|
1131
|
+
`<owner>-<repo>-<hash>` namespace is untouched, `.owenloop/installed.json`
|
|
1132
|
+
keeps its schema and validation, and an explicit `--defs`/`OWENLOOP_DEFS`
|
|
1133
|
+
still installs through a symlinked defs dir (operator intent). The legacy
|
|
1134
|
+
GitHub repository route installs workflow YAML rather than a format-v2
|
|
1135
|
+
`bundle.yaml`; therefore the GitHub route does not carry or enforce the `.wnlp`
|
|
1136
|
+
runtime compatibility declaration and does not provide the `.wnlp` runtime
|
|
1137
|
+
admission guarantee. Use a `.wnlp` bundle when the publisher must declare a
|
|
1138
|
+
minimum Owenloop version or required runtime features.
|
|
1139
|
+
|
|
1140
|
+
The routes share the canonical resolved-store lock, while the GitHub route
|
|
1141
|
+
retains its legacy cwd-derived lock and journal for compatibility. Recovery
|
|
1142
|
+
checks both journal locations and dispatches by journal version; a v2 store
|
|
1143
|
+
journal uses `index.json` metadata and a v1 GitHub journal uses
|
|
1144
|
+
`installed.json` ledger corroboration.
|
|
1145
|
+
|
|
1146
|
+
## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
|
|
1147
|
+
|
|
1148
|
+
These commands authenticate, publish, and start workflows on a hosted **hub** (default
|
|
1149
|
+
`https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
|
|
1150
|
+
`--hub <url>` → `OWENLOOP_HUB` → the built-in `DEFAULT_HUB`. `connect`, `push`,
|
|
1151
|
+
and `publish` use the safer publishing ladder below and never consult
|
|
1152
|
+
`OWENLOOP_HUB` or guess `DEFAULT_HUB`. They are the only network-bound commands
|
|
1153
|
+
besides `add`, and they talk only to endpoints the hub exposes today — no new
|
|
312
1154
|
service-side surface. The hub URL is normalized to its origin
|
|
313
1155
|
(`scheme://host[:port]`); path/query are dropped. `https` is required for
|
|
314
1156
|
every hub origin except the loopback hosts (`127.0.0.1`, `::1`, `localhost`),
|
|
@@ -322,6 +1164,74 @@ bounce credentials or workflow YAML to another origin (same-origin validation
|
|
|
322
1164
|
covers only the initial URL; a redirect would otherwise re-send the request body
|
|
323
1165
|
cross-origin).
|
|
324
1166
|
|
|
1167
|
+
### The small hosted-workflow path
|
|
1168
|
+
|
|
1169
|
+
Setup is durable. Authenticate and bind the project once, publish or update a
|
|
1170
|
+
definition when its content changes, prepare that published version for the
|
|
1171
|
+
execution account, and keep one crew-scoped Shift running:
|
|
1172
|
+
|
|
1173
|
+
```bash
|
|
1174
|
+
owenloop login --hub https://hub.example
|
|
1175
|
+
owenloop connect --hub https://hub.example
|
|
1176
|
+
owenloop push newhire-onboarding
|
|
1177
|
+
OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
|
|
1178
|
+
OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
|
|
1179
|
+
```
|
|
1180
|
+
|
|
1181
|
+
Starting another run does not repeat installation, publication, preparation,
|
|
1182
|
+
or Shift setup. From the connected project it is one public control-plane
|
|
1183
|
+
command; repeat `--provide name=json` for seeded human inputs:
|
|
1184
|
+
|
|
1185
|
+
```bash
|
|
1186
|
+
owenloop start newhire-onboarding \
|
|
1187
|
+
--crew openai \
|
|
1188
|
+
--provide 'signed_docs={"acknowledged":true}' \
|
|
1189
|
+
--provide 'hardware_choice={"laptop":"MacBook Pro"}'
|
|
1190
|
+
```
|
|
1191
|
+
|
|
1192
|
+
`start` always uses the human credential. The standing Shift uses the
|
|
1193
|
+
`agent:default` credential selected by `--as default`. With no project binding,
|
|
1194
|
+
`start --hub <url>` is accepted explicitly; with neither a binding nor `--hub`,
|
|
1195
|
+
it refuses instead of falling through to `OWENLOOP_HUB` or the production
|
|
1196
|
+
default. If both a binding and `--hub` exist they must agree.
|
|
1197
|
+
|
|
1198
|
+
### `start` — start a published workflow
|
|
1199
|
+
|
|
1200
|
+
`owenloop start <defName>` sends `POST /api/start_run` and prints the new
|
|
1201
|
+
workflow id, its initial status, and the steps whose default crew was stamped or
|
|
1202
|
+
whose capability routes were validated. `--crew <name>` selects the crew for
|
|
1203
|
+
steps that declare no capability; capability-bearing steps continue to use
|
|
1204
|
+
their live hub bindings. `--title <text>` is display-only. Both `--crew` and
|
|
1205
|
+
`--title` require non-empty values; bare flags and `--crew=`/`--title=` are local
|
|
1206
|
+
usage errors before credential or network access. The command does not claim,
|
|
1207
|
+
dispatch, close, or otherwise drive work—the standing Shift discovers the run
|
|
1208
|
+
through its normal crew inbox.
|
|
1209
|
+
|
|
1210
|
+
**Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
|
|
1211
|
+
target in this order:
|
|
1212
|
+
|
|
1213
|
+
1. An explicit `--hub <origin>` always wins.
|
|
1214
|
+
2. `.owenloop/hub.json`, when present, is the project override.
|
|
1215
|
+
3. Global machine state supplies one unambiguous candidate:
|
|
1216
|
+
- with the file credential backend, exactly one origin containing a valid
|
|
1217
|
+
human-slot credential is selected automatically;
|
|
1218
|
+
- Keychain and external-command credential backends cannot enumerate their
|
|
1219
|
+
origins, so the validated `hubOrigin` in
|
|
1220
|
+
`$XDG_CONFIG_HOME/owenloop/settings.json` (or
|
|
1221
|
+
`~/.config/owenloop/settings.json`) is used, and the requested credential
|
|
1222
|
+
slot must exist there before the command proceeds.
|
|
1223
|
+
4. If nothing safe resolves, the command exits 2 without network or publication
|
|
1224
|
+
output effects.
|
|
1225
|
+
|
|
1226
|
+
More than one file-backed origin is also an exit-2 ambiguity: the error lists
|
|
1227
|
+
the origins in deterministic order and asks for `--hub <origin>` or
|
|
1228
|
+
`owenloop connect --hub <origin>`. A non-enumerable backend with no settings
|
|
1229
|
+
`hubOrigin` names the exact settings path and asks for the same explicit
|
|
1230
|
+
choice. `owenloop setup` populates that non-secret settings field. `OWENLOOP_HUB`
|
|
1231
|
+
and `DEFAULT_HUB` are intentionally excluded from the publishing ladder because
|
|
1232
|
+
an ambient guess can target the wrong hub organization; ambiguous or missing
|
|
1233
|
+
resolution fails closed instead of choosing one.
|
|
1234
|
+
|
|
325
1235
|
**Request timeouts.** Every hub call — OAuth discovery, client registration,
|
|
326
1236
|
code exchange, token refresh, `whoami`, the workflow list, and each push — is
|
|
327
1237
|
bounded by a 30s deadline; a stalled hub surfaces as a friendly `hub did not
|
|
@@ -397,28 +1307,66 @@ can read (only read) a stored credential through the same backend logic via the
|
|
|
397
1307
|
package's exported `readStoredCredential` — see
|
|
398
1308
|
[Embedding](embedding.md#whats-exported).
|
|
399
1309
|
|
|
1310
|
+
The macOS `security` adapter treats exit status 44 (`errSecItemNotFound`) as the
|
|
1311
|
+
only absence result: lookup returns no credential, and deletion succeeds
|
|
1312
|
+
idempotently (running the same deletion again changes nothing). Every other
|
|
1313
|
+
numeric status, signal termination, or command-start failure is a fatal backend
|
|
1314
|
+
error. Lookup and logout stop at that error; Owenloop neither reports success
|
|
1315
|
+
nor falls through to or deletes a file-store credential. Mapped errors name only
|
|
1316
|
+
the operation and backend failure class, never the service, account, credential,
|
|
1317
|
+
or stdin command.
|
|
1318
|
+
|
|
400
1319
|
**Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
|
|
401
|
-
token, or a `login`/`logout` that stores or deletes a slot — is serialized by
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
1320
|
+
token, or a `login`/`logout` that stores or deletes a slot — is serialized by the
|
|
1321
|
+
logical `credentials.lock` guard and the persistent SQLite lock database at
|
|
1322
|
+
`credentials.lock.sqlite-v2`, both siblings of `credentials.json` in the config
|
|
1323
|
+
dir (created for the keychain backend too, since the race the lock closes is
|
|
1324
|
+
backend-independent). The concern is a token-refresh
|
|
1325
|
+
race: two owenloop processes hitting an expiring OAuth token at once would each
|
|
1326
|
+
POST a refresh and each persist, and because refresh tokens rotate, the second
|
|
1327
|
+
write clobbers the first with a token whose refresh link is already spent —
|
|
1328
|
+
silently killing the credential. Under the lock a process re-reads the slot
|
|
1329
|
+
after acquiring it and, if another process already refreshed, **adopts** that
|
|
1330
|
+
fresh token instead of refreshing again — one network refresh, one write, no
|
|
1331
|
+
lost token. The lock matters only for OAuth refresh and store/delete; read paths
|
|
1332
|
+
and the external-command mode (which never writes the local store) do not take
|
|
1333
|
+
it.
|
|
1334
|
+
|
|
1335
|
+
SQLite owns exclusion through a `BEGIN IMMEDIATE` transaction tied to the live
|
|
1336
|
+
database connection. Release, normal process exit, and process crash close that
|
|
1337
|
+
connection and release the operating-system lock. Owenloop deliberately keeps
|
|
1338
|
+
the SQLite database path after release; Owenloop never deletes or replaces the
|
|
1339
|
+
path. A sibling `credentials.lock.owner.json` contains only diagnostic process
|
|
1340
|
+
metadata and does not determine ownership. If the lock cannot be acquired within
|
|
1341
|
+
the wait budget, the CLI fails loudly (`another owenloop process is using the
|
|
1342
|
+
credential store … — timed out waiting after Ns`) rather than refreshing
|
|
1343
|
+
unlocked. `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000) and
|
|
1344
|
+
`OWENLOOP_CRED_LOCK_POLL_MS` (default 100) override the wait behavior.
|
|
1345
|
+
`OWENLOOP_CRED_LOCK_STALE_MS` is accepted for compatibility but no longer causes
|
|
1346
|
+
pathname deletion. No token value appears in either lock file or the timeout
|
|
1347
|
+
message.
|
|
1348
|
+
|
|
1349
|
+
**Lock-file upgrade boundary.** The logical lock pathname, such as
|
|
1350
|
+
`credentials.lock`, remains a permanent, parseable JSON compatibility guard.
|
|
1351
|
+
The new SQLite lock database lives at `<logical-lock-path>.sqlite-v2`; for the
|
|
1352
|
+
credential store, that path is `credentials.lock.sqlite-v2`. A new client first
|
|
1353
|
+
holds SQLite's `BEGIN IMMEDIATE` transaction and then installs the guard at the
|
|
1354
|
+
old pathname with an exclusive create. The guard carries an impossible operating-
|
|
1355
|
+
system hostname, so a pre-SQLite client treats the guard as a live foreign-host
|
|
1356
|
+
owner and never age-reclaims it. An already-running old holder can release its
|
|
1357
|
+
ordinary JSON lock normally; the waiting new client then installs the guard and
|
|
1358
|
+
closes the one-way upgrade boundary. Old clients remain blocked after every new-
|
|
1359
|
+
client release or crash, while new clients continue to exclude one another
|
|
1360
|
+
through SQLite.
|
|
1361
|
+
|
|
1362
|
+
Release and crash cleanup close only the SQLite transaction. Owenloop never
|
|
1363
|
+
deletes, renames, or replaces either the permanent guard or the versioned SQLite
|
|
1364
|
+
database during normal lock lifecycle. A corrupt, partial, old-owner, or pre-
|
|
1365
|
+
boundary SQLite file already present at the logical legacy pathname fails closed:
|
|
1366
|
+
stop the relevant processes, verify that no old or pre-boundary process still
|
|
1367
|
+
owns that pathname, remove the legacy pathname manually, and let one upgraded
|
|
1368
|
+
client install the permanent guard. Routine stale-age or PID reclamation is no
|
|
1369
|
+
longer used, and `OWENLOOP_CRED_LOCK_STALE_MS` cannot weaken the boundary.
|
|
422
1370
|
|
|
423
1371
|
**Supplying the credential from your own tooling.** If your secrets live in a
|
|
424
1372
|
secret manager, or you run on a host with no keychain, set
|
|
@@ -460,14 +1408,35 @@ it — a `401` there means the credential is never written to disk. On success
|
|
|
460
1408
|
`orgId`, `identity`, and `email` when the hub returns one), read straight from
|
|
461
1409
|
`whoami`.
|
|
462
1410
|
|
|
1411
|
+
**Recording the hub for `owenloop mcp` (`~/.owenloop/config.json`).** After the
|
|
1412
|
+
credential above is verified and stored, `login` makes one more best-effort
|
|
1413
|
+
write: it records the hub origin it just authenticated against in
|
|
1414
|
+
`~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
|
|
1415
|
+
secret, just the origin). This file is separate from both the credential store
|
|
1416
|
+
above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
|
|
1417
|
+
reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
|
|
1418
|
+
which needs to know your hub without enumerating the credential store (the
|
|
1419
|
+
Keychain and external-command backends can't be listed at all — see below). A
|
|
1420
|
+
failure to write this file is a **warning** printed to stderr, never a fatal
|
|
1421
|
+
error and never blocking `login` itself, since the credential is already
|
|
1422
|
+
safely stored by the time this write is attempted. Logging into a second hub
|
|
1423
|
+
overwrites this file — "last login wins" — so if you routinely switch between
|
|
1424
|
+
hubs, pass `--hub` explicitly to `owenloop mcp` (or set `OWENLOOP_HUB`) rather
|
|
1425
|
+
than relying on whichever `login` ran most recently.
|
|
1426
|
+
|
|
463
1427
|
### `connect` — bind a project to a hub
|
|
464
1428
|
|
|
465
|
-
`owenloop connect`
|
|
466
|
-
|
|
467
|
-
/
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
1429
|
+
`owenloop connect` resolves a target through the publishing ladder, re-verifies
|
|
1430
|
+
the stored credential against `GET /api/whoami`, and writes
|
|
1431
|
+
`.owenloop/hub.json`. Run `login` first. With no `--hub`, an existing binding
|
|
1432
|
+
remains the target; an unbound project uses the unambiguous global fallback.
|
|
1433
|
+
An explicit `--hub` creates or replaces the project override, which is useful
|
|
1434
|
+
for multi-org or multi-hub repositories. `connect` is optional for the ordinary
|
|
1435
|
+
single-hub happy path, not a prerequisite for `push` or `publish`.
|
|
1436
|
+
|
|
1437
|
+
The JSON reports the same org/identity fields as `login`; re-connecting to the
|
|
1438
|
+
**same** origin reports no `switchedFrom`, switching to a **different** hub
|
|
1439
|
+
reports `switchedFrom: <old origin>` and rebinds the project to the new one.
|
|
471
1440
|
|
|
472
1441
|
A symlinked project `.owenloop` directory is refused with a clear error rather
|
|
473
1442
|
than followed: a hostile checkout cannot ship `.owenloop -> /elsewhere` to
|
|
@@ -477,16 +1446,40 @@ guarantee). The same refusal covers the default `state.db` FILE (and its SQLite
|
|
|
477
1446
|
file would otherwise redirect the store's writes, since SQLite follows file
|
|
478
1447
|
symlinks.
|
|
479
1448
|
|
|
480
|
-
### `push` — publish local defs to the
|
|
1449
|
+
### `push` — publish local defs to the resolved hub
|
|
481
1450
|
|
|
482
1451
|
`owenloop push [<defName>...]` publishes the project's workflow defs (all of
|
|
483
|
-
them, or just the named ones) to the hub
|
|
1452
|
+
them, or just the named ones) to the hub selected by the publishing ladder.
|
|
1453
|
+
`--hub` overrides a project binding for that invocation without rewriting it;
|
|
1454
|
+
otherwise the project override wins over global state. An unbound project with
|
|
1455
|
+
one file-backed human credential therefore needs no setup step. Ambiguous or
|
|
1456
|
+
missing candidates exit 2 as described above, and `OWENLOOP_HUB`/
|
|
1457
|
+
`DEFAULT_HUB` never participate. `push` never writes a project binding. It
|
|
484
1458
|
reuses the **exact** all-or-nothing validation gate `add` uses — lint, validate,
|
|
485
1459
|
and a bounded `check` — across every selected def before a single byte is sent;
|
|
486
1460
|
any definite defect aborts the whole push. stdout is machine-parseable JSON;
|
|
487
1461
|
the human-readable diff (`+ new`, `~ changed`, `= unchanged`, `! failed`) goes
|
|
488
1462
|
to stderr.
|
|
489
1463
|
|
|
1464
|
+
`owenloop push --bundle <bundle.wnlp> [<defName>...]` is the executable,
|
|
1465
|
+
bundle-backed form. The exact archive is inspected and becomes the definition
|
|
1466
|
+
source; checkout files are ignored. Push requires exactly one adjacent
|
|
1467
|
+
publication sidecar produced by `owenloop publish` (`.dsse` or `.unsigned`),
|
|
1468
|
+
accepts an optional `.origin.dsse`, uploads those content-addressed objects,
|
|
1469
|
+
then calls `create_workflow` with the archive's canonical digest. This is what
|
|
1470
|
+
makes the hub stamp reference orders with a digest that execution hosts can
|
|
1471
|
+
resolve from their installed bundle store. Because a reference order identifies
|
|
1472
|
+
its executable instructions only by bundle digest plus step name, every workflow
|
|
1473
|
+
definition in the complete archive must use distinct step names. `push --bundle`
|
|
1474
|
+
refuses an archive when two definitions share a step name, even when positional
|
|
1475
|
+
arguments select only one of those definitions; the refusal happens before any
|
|
1476
|
+
bundle, evidence, or workflow-version write. Bundle mode conservatively sends
|
|
1477
|
+
each selected `create_workflow` request even when its YAML hash is unchanged,
|
|
1478
|
+
because the workflow listing does not expose the latest bundle identity; the
|
|
1479
|
+
hub's `(yaml, bundle digest)` idempotency decides whether to version-forward or
|
|
1480
|
+
return `noop`. `--dry-run` validates the archive and sidecars and performs only
|
|
1481
|
+
the read-only server diff—no bundle, sidecar, or definition is uploaded.
|
|
1482
|
+
|
|
490
1483
|
**Idempotency is server-side truth, not a client ledger.** `push` fetches the
|
|
491
1484
|
hub's own view of every def (`GET /api/workflows`, which reports each def's
|
|
492
1485
|
`hash`) and diffs local content against it directly — there is no
|
|
@@ -508,6 +1501,15 @@ batch: the current def is recorded as `failed`, the not-yet-attempted remainder
|
|
|
508
1501
|
is reported under a `skipped` output key, and any `Retry-After` the hub sent is
|
|
509
1502
|
surfaced in the error.
|
|
510
1503
|
|
|
1504
|
+
Selected definitions are published in topological `calls:` order. If a selected
|
|
1505
|
+
dependency fails or is skipped, Owenloop sends no `create_workflow` request for
|
|
1506
|
+
its selected dependents; each dependent is added to `skipped`, names its failed
|
|
1507
|
+
or skipped dependencies in sorted order, and becomes unsuccessful so the skip
|
|
1508
|
+
propagates transitively. Independent selected definitions continue publishing.
|
|
1509
|
+
A locally `unchanged` dependency and a server `noop` dependency both count as
|
|
1510
|
+
successful, so either result permits the dependent to publish. Dependency
|
|
1511
|
+
matching covers bare names and same-package-qualified names in a bundle.
|
|
1512
|
+
|
|
511
1513
|
The def hash is computed by re-parsing the raw YAML with no checkout-specific
|
|
512
1514
|
`baseDir` — the same canonicalization the hub applies — so it's portable
|
|
513
1515
|
across checkouts and machines by construction: a fresh clone at a different
|
|
@@ -528,13 +1530,66 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
|
|
|
528
1530
|
resolve the external file against once the YAML leaves this machine. Inline
|
|
529
1531
|
both before pushing.
|
|
530
1532
|
|
|
1533
|
+
### `publish` — pack and publish a workflow bundle
|
|
1534
|
+
|
|
1535
|
+
```text
|
|
1536
|
+
owenloop publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <origin>]
|
|
1537
|
+
```
|
|
1538
|
+
|
|
1539
|
+
`publish` is separate from both [`bundle pack`](#bundles) and [`push`](#push--publish-local-defs-to-the-resolved-hub). It packs one source directory with the same deterministic `packBundle` implementation as `bundle pack`, then publishes the bundle beside a local publication sidecar and, optionally, a signed origin sidecar. A project binding is optional; when present it supplies the project-specific author-key origin unless `--hub` overrides it.
|
|
1540
|
+
|
|
1541
|
+
The author-key origin comes from the same publishing ladder as `connect` and
|
|
1542
|
+
`push`: `--hub` wins, a project binding overrides global state, one file-backed
|
|
1543
|
+
human origin resolves automatically, and a non-enumerable backend uses the
|
|
1544
|
+
validated execution-settings `hubOrigin` only when the human credential exists.
|
|
1545
|
+
An ambiguous or absent candidate exits 2 before signing, packing, or output
|
|
1546
|
+
writes. `publish` never writes `.owenloop/hub.json`, consults `OWENLOOP_HUB`, or
|
|
1547
|
+
guesses `DEFAULT_HUB`.
|
|
1548
|
+
|
|
1549
|
+
Signed publication is the default. In signed mode, `publish` requires the human principal signing key for the resolved hub. Run `owenloop setup` before the first signed publication. `publish` never creates or repairs a signing key: an older key store that already contains the key but lacks the non-secret `<hash>.ref` pointer must be repaired by a setup run, whose `ensure` step backfills the pointer without regenerating or replacing the private key. If the author-key reference or key record is missing, `publish` fails and suggests `owenloop setup` or the explicit unsigned mode; the command does not silently downgrade to unsigned output.
|
|
1550
|
+
|
|
1551
|
+
In signed mode, `publish` confirms the existing key and probes the signer before `packBundle` runs, then signs the publication record before any bundle or sidecar is written. A signing failure therefore leaves no half-published artifact. The signature covers a DSSE publication record whose `digest` is the lowercase SHA-256 digest of the uncompressed canonical tar inside the `.wnlp` file. When `--source <json>` is supplied, the command signs a separate origin record with the same signer and digest, then writes `<output>.origin.dsse` beside the publication sidecar. The remote hub is not involved in this local signing operation and never produces or completes either signature.
|
|
1552
|
+
|
|
1553
|
+
`--source` is signer-supplied provenance, not a hub-derived label. The JSON value must be one of these closed forms:
|
|
1554
|
+
|
|
1555
|
+
- `{"kind":"git","repo":"<repo>","commit":"<40- or 64-hex commit SHA>"}`;
|
|
1556
|
+
- `{"kind":"console","user":"<authoring user>"}`, which requires a client-side signing ceremony; or
|
|
1557
|
+
- `{"kind":"agent","agent":"<agent identity>","session":"<session>"}`.
|
|
1558
|
+
|
|
1559
|
+
The origin record is part of the signed content. The hub or another relay stores and relays the signed record but cannot write, derive, default, or stamp an origin value. `attesterKeyId` in the record is only a candidate-selection hint; verification cross-checks the hint against the signer that produced the verified signature. `--source` cannot be combined with `--unsigned`. The CLI currently rejects the `console` form because that form requires a client-side signing ceremony rather than this command's local signing path.
|
|
1560
|
+
|
|
1561
|
+
`--unsigned` is an explicit opt-in. Unsigned mode still packs the canonical bundle, but writes an unauthenticated author-intent marker rather than a DSSE envelope. Anyone can write such a marker; consumers must treat missing and unverifiable signatures as unsigned regardless of whether the marker is present. Publication and unsigned sidecars are mutually exclusive:
|
|
1562
|
+
|
|
1563
|
+
- signed mode writes `<output>.wnlp.dsse` and removes a stale `<output>.wnlp.unsigned`;
|
|
1564
|
+
- `--unsigned` writes `<output>.wnlp.unsigned` and removes a stale `<output>.wnlp.dsse`.
|
|
1565
|
+
|
|
1566
|
+
A signed publish without `--source` removes a stale `<output>.origin.dsse`. Unsigned mode also removes a stale origin sidecar because an unsigned origin would only be an unsigned label.
|
|
1567
|
+
|
|
1568
|
+
The output defaults to `<package-name>-<version>.wnlp` next to the source directory. `--output` must name a path outside the source directory. Existing regular output and sidecar files may be replaced; directories and other non-regular paths are rejected.
|
|
1569
|
+
|
|
1570
|
+
Successful invocations print exactly one machine-readable JSON object to stdout. Signed output without an origin has this shape:
|
|
1571
|
+
|
|
1572
|
+
```json
|
|
1573
|
+
{
|
|
1574
|
+
"ok": true,
|
|
1575
|
+
"bundle": "/absolute/path/report-1.2.0.wnlp",
|
|
1576
|
+
"digest": "<64 lowercase hex characters>",
|
|
1577
|
+
"name": "report",
|
|
1578
|
+
"version": "1.2.0",
|
|
1579
|
+
"signed": true,
|
|
1580
|
+
"envelope": "/absolute/path/report-1.2.0.wnlp.dsse"
|
|
1581
|
+
}
|
|
1582
|
+
```
|
|
1583
|
+
|
|
1584
|
+
When `--source` is supplied, signed output also includes `"origin": "/absolute/path/report-1.2.0.wnlp.origin.dsse"`. Unsigned output has the same `ok`, `bundle`, `digest`, `name`, and `version` fields, with `"signed": false` and `"marker": "/absolute/path/report-1.2.0.wnlp.unsigned"` instead of `envelope`. Diagnostics and failures go to stderr and exit nonzero. `bundle pack` and `push` are unchanged by this command.
|
|
1585
|
+
|
|
531
1586
|
Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
|
|
532
1587
|
device-code grant remain recorded follow-ups on the service, not gaps in the
|
|
533
1588
|
CLI.
|
|
534
1589
|
|
|
535
1590
|
### `agent new` — mint an agent token into a slot
|
|
536
1591
|
|
|
537
|
-
`owenloop agent new <name>` mints a new
|
|
1592
|
+
`owenloop agent new <name>` mints a new Scoped Identity on the hub (`POST
|
|
538
1593
|
/api/mint_agent_token`, authenticated as your **human** credential) and stores
|
|
539
1594
|
the returned `olp_` token in the local credential slot `agent:<name>` — the same
|
|
540
1595
|
slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
|
|
@@ -544,9 +1599,10 @@ happen in one step, and you never handle the secret.
|
|
|
544
1599
|
**The token is never printed.** The minted `olp_` token goes process → store
|
|
545
1600
|
only — it never appears on stdout, stderr, in an error, or in a log (identity
|
|
546
1601
|
model §6, "rule of gates"). The confirmation JSON is built from a whitelist of
|
|
547
|
-
**non-secret** fields only: `hub`, `name`, `slot`, `
|
|
548
|
-
names), `scopes` (`["work"]`
|
|
549
|
-
|
|
1602
|
+
**non-secret** fields only: `hub`, `name`, `slot`, `crews` (the resolved crew
|
|
1603
|
+
names), `scopes` (the minted token's scopes — `["work"]` by default, or whatever
|
|
1604
|
+
`--scopes`/`--shift` selected), `storage` (`keychain` | `file`), `agentId` (the
|
|
1605
|
+
Scoped Identity's id), and `tokenId` (a revocation handle). To use the Scoped Identity afterwards,
|
|
550
1606
|
pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
|
|
551
1607
|
on the hub.
|
|
552
1608
|
|
|
@@ -562,77 +1618,406 @@ minting on the wrong org is not undone by a retry:
|
|
|
562
1618
|
|
|
563
1619
|
Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
|
|
564
1620
|
built-in default hub — silently defaulting a mint would risk minting on the
|
|
565
|
-
production hub while you're logged into a dev one.
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
1621
|
+
production hub while you're logged into a dev one. This is deliberately
|
|
1622
|
+
stricter than [`owenloop mcp`'s origin resolution](#choosing-the-hub-origin):
|
|
1623
|
+
`mcp` exposes both reads and writes, including `create_agent` (which mints and
|
|
1624
|
+
stores an agent token), `create_workflow`, `publish_event`, `submit`,
|
|
1625
|
+
`stage_enrollment`, and crew mutations. The default remains acceptable for
|
|
1626
|
+
`mcp` because each tool call authenticates against the resolved origin; when no
|
|
1627
|
+
human credential exists there, the existing `loginHint` surfaces the origin
|
|
1628
|
+
and asks for `owenloop login --hub <origin>` before the tool-specific action
|
|
1629
|
+
runs. If a credential does exist at an unintended origin and `create_agent`
|
|
1630
|
+
mints there, the stored agent token is revocable; `--hub` and `OWENLOOP_HUB`
|
|
1631
|
+
remain available when the operator wants to avoid inference. `agent new`
|
|
1632
|
+
**mints** a new credential directly, a side effect a retry cannot undo, so it
|
|
1633
|
+
stops at step 3 instead of ever guessing. Note that hub enumeration itself is
|
|
1634
|
+
**file-store only**: the keychain and the external-command backend cannot list
|
|
1635
|
+
their entries, so on such a machine step 2 cannot enumerate the store and you
|
|
1636
|
+
must pass `--hub`.
|
|
1637
|
+
|
|
1638
|
+
**`--crews <a,b>`.** A comma-separated list of crew names the token is granted
|
|
571
1639
|
on (trimmed, empties dropped). Omit the flag to let the hub default the token to
|
|
572
|
-
the minter's personal
|
|
1640
|
+
the minter's personal crew; `--crews ""` (or `--crews ,`) is a usage error. Crew
|
|
573
1641
|
names are validated by the hub, not the client.
|
|
574
1642
|
|
|
1643
|
+
**`--scopes <a,b>` / `--shift`.** A comma-separated list of scopes the minted
|
|
1644
|
+
token carries (trimmed, empties dropped). Omit both flags to mint **work-only**
|
|
1645
|
+
(the default). `--shift` is shorthand for `--scopes work,run` — the identity
|
|
1646
|
+
a service account needs to both serve and *start* runs. The two flags are
|
|
1647
|
+
mutually exclusive (`--scopes … --shift` together is a usage error), and
|
|
1648
|
+
`--scopes ""` (or `--scopes ,`) is a usage error. Scope names are validated by
|
|
1649
|
+
the hub, not the client.
|
|
1650
|
+
|
|
575
1651
|
**A configured external credential command blocks the mint.** If
|
|
576
1652
|
`OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
|
|
577
1653
|
supplies credentials for the hub, so `agent new` refuses up front (it has
|
|
578
1654
|
nowhere to write the minted token); unset the variable to use the local store.
|
|
579
|
-
This check, the name validation,
|
|
580
|
-
|
|
581
|
-
|
|
1655
|
+
This check, the name validation, the empty-`--crews` check, the empty-`--scopes`
|
|
1656
|
+
check, and the `--scopes`/`--shift` mutual-exclusivity check all run
|
|
1657
|
+
**before** any network call, so a refusal never mints a server-side token first
|
|
1658
|
+
— a mint that then failed to store would burn the agent name permanently.
|
|
582
1659
|
|
|
583
1660
|
**Exit codes.**
|
|
584
1661
|
|
|
585
1662
|
| code | meaning |
|
|
586
1663
|
|---|---|
|
|
587
1664
|
| `0` | minted and stored |
|
|
588
|
-
| `1` | generic failure — invalid or already-taken name,
|
|
1665
|
+
| `1` | generic failure — invalid or already-taken name, crew/shape rejection, network timeout, or a token that minted but couldn't be stored |
|
|
589
1666
|
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
590
1667
|
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
591
1668
|
|
|
592
|
-
##
|
|
1669
|
+
## Capability routes
|
|
1670
|
+
|
|
1671
|
+
A **capability route** maps a workflow-def **capability** (a logical capability tag a
|
|
1672
|
+
def author writes, like `gpu` or `repo-access`) to a **crew** on one hub org.
|
|
1673
|
+
Def authors write capabilities; an org admin binds each capability to at least one crew.
|
|
1674
|
+
That indirection is what keeps deployment facts out of portable defs — see
|
|
1675
|
+
[`capabilities:`](authoring.md#capabilities--logical-capability-tags) in the authoring guide
|
|
1676
|
+
for the step-side declaration.
|
|
1677
|
+
|
|
1678
|
+
**A route is one `(capability, crew)` PAIR, and a capability may bind MANY crews.** The
|
|
1679
|
+
pair is the unit that is created and destroyed: `capability bind` adds one, `capability unbind` removes one, and `capability list` returns one row per pair — so a capability bound
|
|
1680
|
+
to three crews appears as three rows. A **dangling route** is one whose crew
|
|
1681
|
+
row was deleted; it survives in the table, routes nothing, and never widens
|
|
1682
|
+
access. A capability with **zero live routes** is **parked**: its steps wait.
|
|
1683
|
+
|
|
1684
|
+
**Resolution is live.** `start_run` only *checks* that every capability a run's steps
|
|
1685
|
+
use is currently bound — it stamps no crew for a capability-routed step. Every later
|
|
1686
|
+
routing decision (which Shift is offered the step, and whether a claim is
|
|
1687
|
+
allowed) re-reads the route table as it stands at that moment.
|
|
1688
|
+
|
|
1689
|
+
**These edits take effect on work already in flight.**
|
|
1690
|
+
|
|
1691
|
+
- **Adding.** Running `capability bind` on a capability that is **already bound** ADDS the
|
|
1692
|
+
named crew — it never displaces a crew already bound. Adding widens who can
|
|
1693
|
+
serve the capability, live at the next poll of every in-flight run using it. Re-adding
|
|
1694
|
+
a pair that is already there is a normal success, not an error (`alreadyRouted:
|
|
1695
|
+
true`).
|
|
1696
|
+
- **Removing.** Running `capability unbind` removes exactly ONE pair. If the capability still
|
|
1697
|
+
has other live routes, it simply routes to a narrower set and nothing pauses.
|
|
1698
|
+
If the removal takes away the **last live** route, the capability is **parked**:
|
|
1699
|
+
the in-flight steps that use it are offered to no Shift and accept no
|
|
1700
|
+
claim — until it is bound again. Nothing is lost; the work resumes on re-bind.
|
|
1701
|
+
`remainingCrewIds: []` on stdout is that signal, and stderr says so in words.
|
|
1702
|
+
- **Retargeting is two acts, not one.** There is no retarget command: add the new
|
|
1703
|
+
crew, then remove the old one. Each is separately audited on the hub, and in
|
|
1704
|
+
between **BOTH** crews serve the capability. The CLI deliberately does not chain the
|
|
1705
|
+
two for you — the intermediate state is a real state an operator may want to sit
|
|
1706
|
+
in, and collapsing it would hide a widened access window.
|
|
1707
|
+
|
|
1708
|
+
A capability route is **not** the project↔hub binding `owenloop connect` writes to
|
|
1709
|
+
`.owenloop/hub.json` — that one records which hub *this project directory*
|
|
1710
|
+
publishes to; a capability route is an org-scoped capability→crew row on the hub.
|
|
1711
|
+
|
|
1712
|
+
### `capability bind <capability> <crew>`
|
|
1713
|
+
|
|
1714
|
+
`POST /api/add_capability_route`, authenticated as your **human** credential;
|
|
1715
|
+
requires the **admin** role on the hub. ADDS the crew named `<crew>` to
|
|
1716
|
+
`<capability>`'s routes. `<crew>` is a crew **name** — the hub resolves it to a crew
|
|
1717
|
+
id; the CLI does no crew lookup and performs no client-side validation of either
|
|
1718
|
+
argument (the hub is the enforcement of record).
|
|
1719
|
+
|
|
1720
|
+
**Adding is idempotent per pair.** Re-adding a `(capability, crew)` pair that is
|
|
1721
|
+
already bound is a normal success — the hub answers `200` with `alreadyRouted:
|
|
1722
|
+
true` and changes nothing (the original row keeps its creator and timestamp).
|
|
1723
|
+
`routedCrewCount` reports how many **live** crews the capability binds after the write.
|
|
1724
|
+
|
|
1725
|
+
### `capability unbind <capability> <crew>`
|
|
1726
|
+
|
|
1727
|
+
`POST /api/remove_capability_route`, authenticated as your **human** credential;
|
|
1728
|
+
requires the **admin** role on the hub. Removes the ONE `(capability, crew)` route
|
|
1729
|
+
you name. `<crew>` is **required**: a capability may bind many crews, so a capability-only
|
|
1730
|
+
removal would unbind more than you asked for.
|
|
1731
|
+
|
|
1732
|
+
`<crew>` accepts the crew's **name**, or its raw **`crew_id`**. The raw-id form
|
|
1733
|
+
is the only way to remove a **dangling** route — one whose crew row was
|
|
1734
|
+
deleted, so there is no name left to resolve. `capability list` shows such a row
|
|
1735
|
+
with `crewName: null`; take its `crewId` from there.
|
|
1736
|
+
|
|
1737
|
+
**`rm` is idempotent.** Removing a pair that is **not** bound is a normal
|
|
1738
|
+
success — the hub answers `200` with `removed: false` rather than a `404` — and
|
|
1739
|
+
the CLI prints a full document plus a stderr line saying nothing was removed. A
|
|
1740
|
+
script can call `capability unbind` unconditionally without branching on whether the
|
|
1741
|
+
pair was bound. On that tolerant path `crewId` is `null`, because the argument
|
|
1742
|
+
matched neither a live crew name nor one of the capability's own rows.
|
|
1743
|
+
|
|
1744
|
+
**Removing the last live route parks the capability**, and stderr says so. See
|
|
1745
|
+
"These edits take effect on work already in flight" above.
|
|
1746
|
+
|
|
1747
|
+
### `capability list`
|
|
1748
|
+
|
|
1749
|
+
`GET /api/capability_routes`, authenticated as your **human** credential. Lists the
|
|
1750
|
+
org's routes, ONE row per `(capability, crew)` pair ordered by capability then crew id —
|
|
1751
|
+
so a capability bound to several crews appears as several rows. An org with no
|
|
1752
|
+
routes yet is a normal success (exit 0) with an empty `routes` array.
|
|
1753
|
+
|
|
1754
|
+
A row whose `crewName` is `null` is a **dangling route**: the crew it names was
|
|
1755
|
+
deleted. Such a row routes nothing and never widens access, and it is shown
|
|
1756
|
+
rather than hidden precisely so you can clean it up — remove it with `capability unbind
|
|
1757
|
+
<capability> <crewId>`.
|
|
1758
|
+
|
|
1759
|
+
**Flags.** `--hub <url>` only (plus the global `--db`/`--defs`).
|
|
1760
|
+
|
|
1761
|
+
**Which hub gets acted on (`--hub`).** Resolution is deliberately narrow — the
|
|
1762
|
+
same stance `agent new` takes, because a route written against the wrong org
|
|
1763
|
+
is not undone by a retry, and under live resolution it also moves in-flight
|
|
1764
|
+
work:
|
|
593
1765
|
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
1766
|
+
1. `--hub <origin>` if given (normalized the same way as everywhere else).
|
|
1767
|
+
2. Otherwise the **one** hub your credential *file* stores — if exactly one is
|
|
1768
|
+
present, it's used.
|
|
1769
|
+
3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
|
|
1770
|
+
in to exactly one hub); when more than one hub is stored their origins are
|
|
1771
|
+
listed back so you can pick.
|
|
1772
|
+
|
|
1773
|
+
This does **not** fall back to `OWENLOOP_HUB` or the built-in default hub. Note
|
|
1774
|
+
that hub enumeration is **file-store only**: the keychain and the
|
|
1775
|
+
external-command backend cannot list their entries, so on such a machine step 2
|
|
1776
|
+
cannot enumerate the store and you must pass `--hub`.
|
|
1777
|
+
|
|
1778
|
+
**Printed JSON.** stdout is exactly one whitelisted JSON document per
|
|
1779
|
+
invocation, built from named fields — never a raw hub body — so `| jq` always
|
|
1780
|
+
works. Human progress lines (the two `capability unbind` warnings) go to stderr only.
|
|
1781
|
+
|
|
1782
|
+
| subcommand | stdout |
|
|
1783
|
+
|---|---|
|
|
1784
|
+
| `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyRouted": false, "routedCrewCount": 2 }` |
|
|
1785
|
+
| `capability unbind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crewId": "crw_1", "removed": true, "remainingCrewIds": ["crw_2"] }` |
|
|
1786
|
+
| `capability list` | `{ "ok": true, "hub": "<origin>", "routes": [ { "capability": "gpu", "crewId": "crw_1", "crewName": "ml-crew", "createdBy": "u_1", "createdAt": 1738000000000 } ] }` |
|
|
1787
|
+
|
|
1788
|
+
Every added field carries the **hub's own name**, verbatim — the same words its
|
|
1789
|
+
audit log and the web console use — so correlating stdout against them never
|
|
1790
|
+
needs a translation step.
|
|
1791
|
+
|
|
1792
|
+
- `alreadyRouted` (`capability bind`) — was this exact `(capability, crew)` pair already
|
|
1793
|
+
bound before the call? `false` means the pair was created by it.
|
|
1794
|
+
- `routedCrewCount` (`capability bind`) — how many **live** crews the capability binds
|
|
1795
|
+
after the write. A dangling route routes nothing and is not counted.
|
|
1796
|
+
- `removed` (`capability unbind`) — did this call actually remove a pair? `false` is the
|
|
1797
|
+
tolerant "it was never bound" case, not an error.
|
|
1798
|
+
- `remainingCrewIds` (`capability unbind`) — the **live** crews the capability still binds.
|
|
1799
|
+
`[]` means the capability is now **parked**: `jq '.remainingCrewIds | length == 0'`.
|
|
1800
|
+
It can be `[]` while a dangling row survives, because such a row routes nothing.
|
|
1801
|
+
- `crewId` (`capability unbind`) — the crew the hub resolved your `<crew>` argument to.
|
|
1802
|
+
It is `null` on the tolerant `removed: false` path, where the argument matched
|
|
1803
|
+
neither a live crew name nor one of the capability's own route rows. `capability unbind`
|
|
1804
|
+
never prints a crew *name*: `remove_capability_route` does not return one, and
|
|
1805
|
+
inventing one from argv would not be the hub's answer.
|
|
1806
|
+
- `capability` and `crew` (`capability bind`) are the values the **hub** echoed back, not
|
|
1807
|
+
your argv: if the hub normalized either, stdout tells the truth about what was
|
|
1808
|
+
stored.
|
|
1809
|
+
|
|
1810
|
+
**Exit codes.**
|
|
1811
|
+
|
|
1812
|
+
| code | meaning |
|
|
1813
|
+
|---|---|
|
|
1814
|
+
| `0` | the crew was added to the capability (or was already bound), the route was removed (or was already absent), or the routes were listed |
|
|
1815
|
+
| `1` | runtime or hub error — an unknown crew name (`capability bind` only; `capability unbind` answers a tolerant `removed: false` instead), a capability that fails the hub's name rules, a `403` for a non-admin, a malformed response, or a network timeout |
|
|
1816
|
+
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
1817
|
+
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
1818
|
+
|
|
1819
|
+
## Crews
|
|
1820
|
+
|
|
1821
|
+
A **crew** is an org-scoped queue that agent work is stamped to. Every hub org
|
|
1822
|
+
can have, in addition to any crews an admin creates, one **orphan crew** (name
|
|
1823
|
+
`orphan:unrouted`, `kind: "orphan"`) that the hub itself owns as the landing
|
|
1824
|
+
zone for work whose crew was deleted out from under it. It is materialized
|
|
1825
|
+
**lazily**, the first time a crew holding stamped work is deleted — an org
|
|
1826
|
+
that has never deleted a crew with stamped work has no orphan crew at all, and
|
|
1827
|
+
`crew list` shows none. Once it exists, `crew list` includes it — it is
|
|
1828
|
+
marked, never hidden, via a derived `orphan: true` boolean on its row (see the
|
|
1829
|
+
Printed JSON table below).
|
|
1830
|
+
|
|
1831
|
+
This family is independent of [capability routes](#capability-routes): a capability routes
|
|
1832
|
+
to a crew by *name*, and a crew is where agent work actually queues. Deleting a
|
|
1833
|
+
crew a capability still points at does not error — the capability's routing simply
|
|
1834
|
+
resolves nowhere useful until it is rebound.
|
|
1835
|
+
|
|
1836
|
+
### `crew list`
|
|
1837
|
+
|
|
1838
|
+
`GET /api/crews`, authenticated as your **human** credential. Lists the org's
|
|
1839
|
+
crews, each with its member rows (`principalKind`/`principalId`/`addedBy`/
|
|
1840
|
+
`addedAt`). An org with no crews at all — including one that has never
|
|
1841
|
+
materialized an orphan crew — is still a normal success (exit 0) with an empty
|
|
1842
|
+
`crews` array.
|
|
1843
|
+
|
|
1844
|
+
### `crew new <name> --kind personal|shared [--owner <memberId>]`
|
|
1845
|
+
|
|
1846
|
+
`POST /api/create_crew`, authenticated as your **human** credential; requires
|
|
1847
|
+
the **admin** role on the hub, **or** — for `--kind personal --owner
|
|
1848
|
+
<memberId>` where `<memberId>` is the caller's own member id — no admin role
|
|
1849
|
+
at all: a human may self-service additional personal crews for themself
|
|
1850
|
+
without being an admin (`assertPoolMutationAllowed`, hub-core
|
|
1851
|
+
`manage-crews.ts:211-214`). Every other combination (a `shared` crew, or a
|
|
1852
|
+
`personal` crew owned by someone else) still requires admin. `--kind` is **required** but its value is
|
|
1853
|
+
forwarded to the hub **verbatim and unvalidated** — the hub is the enforcement
|
|
1854
|
+
of record for which kind values are legal (today `personal`/`shared`; `orphan`
|
|
1855
|
+
is reserved for the hub's own crew). `--owner <memberId>` is optional and is
|
|
1856
|
+
omitted from the request body entirely when not given — a `personal` crew
|
|
1857
|
+
with no owner is the hub's own error to raise, not a client-side rule
|
|
1858
|
+
duplicated here.
|
|
1859
|
+
|
|
1860
|
+
### `crew rm <crewId>`
|
|
1861
|
+
|
|
1862
|
+
`POST /api/delete_crew`, authenticated as your **human** credential; requires
|
|
1863
|
+
the **admin** role on the hub for every crew kind, including a personal one —
|
|
1864
|
+
`deletePool` bypasses the self-service gate that `crew new`/`crew member
|
|
1865
|
+
add`/`crew member rm` use, and is admin-only unconditionally
|
|
1866
|
+
(`manage-crews.ts:629`). Deletes the crew. The crew's **membership rows are
|
|
1867
|
+
deleted outright, not moved** — `deleteAllPoolMembers` (`manage-crews.ts:706`)
|
|
1868
|
+
runs unconditionally in the same transaction, whether or not any stamps
|
|
1869
|
+
transfer; `membersRemoved` on stdout is a count of those deletions, since the
|
|
1870
|
+
orphan crew's own membership is derived (always the org's current admins) and
|
|
1871
|
+
cannot accept arbitrary members. Only the crew's **run stamps and
|
|
1872
|
+
queued/running work** move to the org's orphan crew — memberships are never
|
|
1873
|
+
among what moves.
|
|
1874
|
+
|
|
1875
|
+
**`rm` is idempotent.** Deleting a `<crewId>` that does not exist is a normal
|
|
1876
|
+
success — the hub answers `200` with `deleted: false` rather than a `404` —
|
|
1877
|
+
and the CLI prints this honestly (see below), plus a stderr line naming the
|
|
1878
|
+
crew id, rather than inventing an error.
|
|
1879
|
+
|
|
1880
|
+
**Like [`capability unbind`](#capability-unbind-capability-crew), `crew rm` prints its tolerant
|
|
1881
|
+
boolean on stdout** — `deleted` here, `removed` there. Both families report
|
|
1882
|
+
honestly whether the call actually changed anything, and both narrate the
|
|
1883
|
+
no-op case on stderr, so a script can branch on the boolean and a human reading
|
|
1884
|
+
the terminal is told in words.
|
|
1885
|
+
|
|
1886
|
+
**The transfer fields are present on stdout if and only if the wire sent
|
|
1887
|
+
them** — `membersRemoved`, `orphanCrewId`, `orphanCrewName`,
|
|
1888
|
+
`stampsTransferred`, `runsTransferred` (an array of run ids, not a count), and
|
|
1889
|
+
`runningRunsTransferred` (the subset still running, also an array) are never
|
|
1890
|
+
defaulted to `0`/`null`/`[]`. Their absence means nothing moved; their
|
|
1891
|
+
presence means a transfer happened, and stderr also gets a one-line human
|
|
1892
|
+
summary naming the destination crew.
|
|
1893
|
+
|
|
1894
|
+
### `crew member add <crewId> <principalKind> <principalId>`
|
|
1895
|
+
|
|
1896
|
+
`POST /api/add_crew_member` authenticated as your **human** credential;
|
|
1897
|
+
requires the **admin** role on the hub, **or** the owner of the personal crew
|
|
1898
|
+
being acted on (same self-service carve-out as `crew new`, gated on the
|
|
1899
|
+
fetched crew row rather than the raw request — `manage-crews.ts:300`). Adds
|
|
1900
|
+
`<principalId>` (a member id or an agent id) to the crew as a
|
|
1901
|
+
`<principalKind>` (`member` or `agent`) member. `<principalKind>` is forwarded
|
|
1902
|
+
verbatim and unvalidated, same stance as `--kind` on `crew new`.
|
|
1903
|
+
|
|
1904
|
+
**The hub refuses this outright against the org's orphan crew, for every
|
|
1905
|
+
caller — including an admin.** `assertNotOrphanPool` (`manage-crews.ts:307`)
|
|
1906
|
+
throws before the add ever reaches the membership table, and it is a `400`,
|
|
1907
|
+
never a `403`: the refusal is identity-independent (true for every caller, not
|
|
1908
|
+
a permissions question), so a `403` would wrongly point the caller at their
|
|
1909
|
+
own role. The orphan crew's membership is derived — always the org's current
|
|
1910
|
+
admins, reconciled automatically on every membership change — and cannot be
|
|
1911
|
+
edited directly.
|
|
1912
|
+
|
|
1913
|
+
### `crew member rm <crewId> <principalId>`
|
|
1914
|
+
|
|
1915
|
+
`POST /api/remove_crew_member`, authenticated as your **human** credential;
|
|
1916
|
+
requires the **admin** role on the hub, **or** the owner of the personal crew
|
|
1917
|
+
being acted on (`manage-crews.ts:356`). Removes `<principalId>` from the crew.
|
|
1918
|
+
|
|
1919
|
+
**`member rm` is idempotent**, mirroring `crew rm`: removing a principal that
|
|
1920
|
+
was never a member of `<crewId>` is a normal `200` with `removed: false`, never
|
|
1921
|
+
a `404`. The CLI prints `removed: false` on stdout and a stderr line naming
|
|
1922
|
+
the principal and crew, rather than treating it as an error.
|
|
1923
|
+
|
|
1924
|
+
**Same orphan-crew refusal as `crew member add`.** Targeting the orphan crew
|
|
1925
|
+
is a `400` here too (`assertNotOrphanPool`, `manage-crews.ts:363`), for every
|
|
1926
|
+
caller including an admin, and for the same reason: the membership is derived,
|
|
1927
|
+
not editable.
|
|
1928
|
+
|
|
1929
|
+
**Flags.** `--hub <url>` only (plus the global `--db`/`--defs`), except `crew
|
|
1930
|
+
new`, which also takes `--kind` (required) and `--owner` (optional).
|
|
1931
|
+
|
|
1932
|
+
**Which hub gets acted on (`--hub`).** Identical resolution to the capability-route family: `--hub` if given, else the one hub your credential file stores, else
|
|
1933
|
+
exit 2 naming both remedies (and, on a multi-hub machine, listing the stored
|
|
1934
|
+
origins). No fallback to `OWENLOOP_HUB`
|
|
1935
|
+
or the built-in default hub; hub enumeration is file-store only.
|
|
1936
|
+
|
|
1937
|
+
**Printed JSON.** stdout is exactly one whitelisted JSON document per
|
|
1938
|
+
invocation — never a raw hub body — so `| jq` always works. Human-facing
|
|
1939
|
+
lines (the tolerant-false notices, the transfer summary) go to stderr only.
|
|
1940
|
+
|
|
1941
|
+
| subcommand | stdout |
|
|
1942
|
+
|---|---|
|
|
1943
|
+
| `crew list` | `{ "ok": true, "hub": "<origin>", "crews": [ { "id": "crw_1", "name": "team-a", "kind": "shared", "ownerMemberId": null, "createdBy": "u_1", "createdAt": 1738000000000, "orphan": false, "members": [ { "principalKind": "member", "principalId": "u_2", "addedBy": "u_1", "addedAt": 1738000000000 } ] } ] }` |
|
|
1944
|
+
| `crew new` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "name": "team-a", "kind": "shared", "ownerMemberId": null }` |
|
|
1945
|
+
| `crew rm` (no transfer) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "deleted": true, "membersRemoved": 2 }` |
|
|
1946
|
+
| `crew rm` (with transfer) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "deleted": true, "membersRemoved": 2, "orphanCrewId": "crw_orphan", "orphanCrewName": "orphan:unrouted", "stampsTransferred": 5, "runsTransferred": ["run_1", "run_2"], "runningRunsTransferred": ["run_2"] }` |
|
|
1947
|
+
| `crew rm` (unknown id) | `{ "ok": true, "hub": "<origin>", "crewId": "crw_bogus", "deleted": false }` |
|
|
1948
|
+
| `crew member add` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalKind": "member", "principalId": "u_2" }` |
|
|
1949
|
+
| `crew member rm` | `{ "ok": true, "hub": "<origin>", "crewId": "crw_1", "principalId": "u_2", "removed": true }` |
|
|
1950
|
+
|
|
1951
|
+
**Exit codes.**
|
|
1952
|
+
|
|
1953
|
+
| code | meaning |
|
|
1954
|
+
|---|---|
|
|
1955
|
+
| `0` | the crew/membership was listed, created, removed (or was already absent) |
|
|
1956
|
+
| `1` | runtime or hub error — an unknown crew id on a member add/rm, a crew with active work refusing deletion, a `403` for a non-admin, a malformed response, or a network timeout |
|
|
1957
|
+
| `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
|
|
1958
|
+
| `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
|
|
1959
|
+
|
|
1960
|
+
## `setup` — onboard a machine
|
|
1961
|
+
|
|
1962
|
+
`owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
|
|
1963
|
+
Depending on the machine state, setup may store the human credential, mint or
|
|
1964
|
+
rekey and store a Scoped Identity credential, ensure the three principal
|
|
1965
|
+
signing keys, relay a signed machine enrollment grant, and write only
|
|
1966
|
+
`hubOrigin` in the execution settings file while preserving its other keys.
|
|
1967
|
+
The plugin step probes and, when needed, converges the bundled `owenloop` plugin
|
|
1968
|
+
for each available harness: Claude Code and Codex. Plugin convergence is
|
|
1969
|
+
non-fatal and setup continues when a harness is missing, the bundled marketplace
|
|
1970
|
+
root is unavailable, or a plugin command fails. A second run with the expected
|
|
1971
|
+
plugin version already installed performs no plugin writes. The steps:
|
|
599
1972
|
|
|
600
1973
|
1. **inspect** — read-only report of what's already present (human credential,
|
|
601
|
-
|
|
1974
|
+
execution settings, `claude` and `codex` on PATH, agent slots). No writes.
|
|
602
1975
|
2. **human login** — verify the stored **human** credential, or run the same
|
|
603
1976
|
loopback-OAuth browser flow as `owenloop login` when none is present or it no
|
|
604
1977
|
longer verifies. This is the gate that makes step 3's mint/rekey legal.
|
|
605
1978
|
3. **agent** — find a local `agent:<name>` slot that verifies live against the
|
|
606
|
-
hub and reuse it; otherwise **mint** a new
|
|
1979
|
+
hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
|
|
607
1980
|
(replace the credential of) an existing one. How the target is chosen is
|
|
608
|
-
[below](#choosing-the-
|
|
609
|
-
4. **
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
1981
|
+
[below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
|
|
1982
|
+
4. **signing keys** — ensure an Ed25519 signing key for each of the three local
|
|
1983
|
+
principals, in order: human, machine, agent. Details
|
|
1984
|
+
[below](#signing-keys-step-4). After key convergence, setup performs the
|
|
1985
|
+
enrollment relay sub-step described below.
|
|
1986
|
+
5. **execution settings** — write only `hubOrigin` into the execution settings
|
|
1987
|
+
file so the local Step Agent talks to this hub, preserving every other key
|
|
1988
|
+
(skipped when `hubOrigin` already matches).
|
|
1989
|
+
6. **plugin** — probe and converge the bundled `owenloop` plugin separately
|
|
1990
|
+
for Claude Code and Codex. When the installed plugin is missing or its
|
|
1991
|
+
version differs from the CLI package, setup adds the bundled marketplace
|
|
1992
|
+
when needed and installs or updates the plugin. Claude Code uses
|
|
1993
|
+
`claude plugin install` for a fresh install and `claude plugin update` for
|
|
1994
|
+
an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
|
|
1995
|
+
fresh installs and upgrades; setup does not call
|
|
1996
|
+
`codex plugin marketplace upgrade`, which applies only to Git marketplaces.
|
|
1997
|
+
**Non-fatal:** a missing harness or failed convergence is reported as
|
|
1998
|
+
`noted` and never fails setup. If the bundled marketplace root is
|
|
1999
|
+
unavailable, setup prints manual commands instead.
|
|
2000
|
+
7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
|
|
616
2001
|
the same surfaces, whose result becomes setup's exit code.
|
|
617
2002
|
|
|
618
|
-
Progress lines (the `[n/
|
|
2003
|
+
Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
619
2004
|
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
620
2005
|
**stdout**.
|
|
621
2006
|
|
|
622
|
-
### Choosing the
|
|
2007
|
+
### Choosing the Scoped Identity (Flow A vs Flow B)
|
|
623
2008
|
|
|
624
|
-
When step 3 has to act (no reusable local agent slot), it decides *which*
|
|
2009
|
+
When step 3 has to act (no reusable local agent slot), it decides *which* Scoped Identity
|
|
625
2010
|
to connect this machine to:
|
|
626
2011
|
|
|
627
|
-
- **Flow A — fresh org (no
|
|
628
|
-
**name** the
|
|
2012
|
+
- **Flow A — fresh org (no Scoped Identities on the hub):** setup asks you to
|
|
2013
|
+
**name** the Scoped Identity, prefilled with a sanitized form of the machine hostname.
|
|
629
2014
|
The name is a suggestion — any label matching `[A-Za-z0-9][A-Za-z0-9._-]*`
|
|
630
|
-
(1–64 chars) is accepted. It then **mints** that
|
|
631
|
-
- **Flow B — org already has
|
|
632
|
-
|
|
2015
|
+
(1–64 chars) is accepted. It then **mints** that Scoped Identity.
|
|
2016
|
+
- **Flow B — org already has Scoped Identities (succession):** setup shows the existing
|
|
2017
|
+
Scoped Identities (each with its name, when it was **last active**, and its **crews**)
|
|
633
2018
|
and asks whether this is a *new* installation or one that *replaces* an
|
|
634
|
-
existing
|
|
635
|
-
**rekeys** the chosen
|
|
2019
|
+
existing Scoped Identity. Choosing **new** mints a fresh Scoped Identity; choosing **replace**
|
|
2020
|
+
**rekeys** the chosen Scoped Identity — which **revokes that Scoped Identity's current
|
|
636
2021
|
credential**, so if it is still running elsewhere it will be disconnected
|
|
637
2022
|
there.
|
|
638
2023
|
|
|
@@ -640,15 +2025,101 @@ to connect this machine to:
|
|
|
640
2025
|
scripted or piped run) and step 3 needs to act, setup will not block on a
|
|
641
2026
|
prompt — it errors unless you pre-decide with one of:
|
|
642
2027
|
|
|
643
|
-
- `--new-agent <name>` — mint a new
|
|
2028
|
+
- `--new-agent <name>` — mint a new Scoped Identity named `<name>` (skips Flow A's name
|
|
644
2029
|
prompt and Flow B's succession prompt).
|
|
645
|
-
- `--replace-agent <name>` — rekey the existing
|
|
646
|
-
succession prompt); errors if no such
|
|
2030
|
+
- `--replace-agent <name>` — rekey the existing Scoped Identity named `<name>` (skips the
|
|
2031
|
+
succession prompt); errors if no such Scoped Identity exists on the hub.
|
|
647
2032
|
|
|
648
|
-
The two flags are mutually exclusive. `--
|
|
2033
|
+
The two flags are mutually exclusive. `--crews <a,b>` applies **only** to a mint
|
|
649
2034
|
(`--new-agent` or a fresh org); combining it with `--replace-agent` is a usage
|
|
650
|
-
error, because rekeying preserves the
|
|
651
|
-
the console).
|
|
2035
|
+
error, because rekeying preserves the Scoped Identity's existing crews (manage those in
|
|
2036
|
+
the console). `--scopes <a,b>` likewise applies **only** to a mint — it selects
|
|
2037
|
+
the minted token's scopes (default `work`); combining it with `--replace-agent`
|
|
2038
|
+
is a usage error, because rekeying preserves the Scoped Identity's existing scopes (mint a
|
|
2039
|
+
new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
|
|
2040
|
+
scopes out with `--scopes work,run`.
|
|
2041
|
+
|
|
2042
|
+
### Signing keys (step 4)
|
|
2043
|
+
|
|
2044
|
+
Step 4 ensures one Ed25519 signing key per local principal — human, machine,
|
|
2045
|
+
agent — keyed by `{ hub origin, kind, principal id }`. It is **idempotent**:
|
|
2046
|
+
an existing key reports `existing` and is never regenerated or rewritten. A
|
|
2047
|
+
second full setup run performs zero key writes.
|
|
2048
|
+
|
|
2049
|
+
**Storage backends.** The key record goes to the macOS Keychain
|
|
2050
|
+
(`security`), to Linux libsecret (`secret-tool`) when that binary is on
|
|
2051
|
+
`PATH`, and otherwise to a `0600` file under `$HOME/.owenloop/keys/` (both
|
|
2052
|
+
parent directories forced `0700`, symlinks refused). One backend is selected
|
|
2053
|
+
once and a failure is a hard error — there is never a fallback to another
|
|
2054
|
+
backend, because a fallback could mint a second, different key for the same
|
|
2055
|
+
principal. `OWENLOOP_NO_KEYCHAIN=1` forces the file backend. Private bytes
|
|
2056
|
+
never appear on argv or in setup output.
|
|
2057
|
+
|
|
2058
|
+
**`--reuse-ssh-key <path>`** records your own existing Ed25519 SSH key for the
|
|
2059
|
+
**human** principal instead of generating one. The candidate is validated with
|
|
2060
|
+
a non-secret sign/verify challenge before anything is recorded, and only its
|
|
2061
|
+
canonical path + public key are stored — the private key is never copied. It
|
|
2062
|
+
applies to the human key only (machine and agent always get generated keys),
|
|
2063
|
+
and it is a **hard conflict** when a human key already exists: setup keeps the
|
|
2064
|
+
existing key and errors rather than rotating (rotation is not part of this
|
|
2065
|
+
work package). A nonexistent path fails up front, before any browser opens.
|
|
2066
|
+
|
|
2067
|
+
**Secret-output guarantee.** Step 4 prints only `kind state (backend)` — e.g.
|
|
2068
|
+
`✓ signing keys: human created (macos-security), machine created (file), agent
|
|
2069
|
+
existing (macos-security)` — never key bytes, fingerprints, or secret-store
|
|
2070
|
+
values. The full storage and signing model is in
|
|
2071
|
+
[Signing and key storage](crypto.md).
|
|
2072
|
+
|
|
2073
|
+
### Machine enrollment relay
|
|
2074
|
+
|
|
2075
|
+
After the three keys are ensured, setup tries to register the machine public key
|
|
2076
|
+
with the hub. The relay is deliberately subordinate to local key convergence:
|
|
2077
|
+
|
|
2078
|
+
1. Read-only inspect the human signing key. If no human signing key is present,
|
|
2079
|
+
setup records `skipped` and performs no enrollment request.
|
|
2080
|
+
2. `GET /api/enrollments` with the human credential. If the hub is unavailable,
|
|
2081
|
+
returns an unsupported status such as `404`, returns `500`, or returns an
|
|
2082
|
+
unusable response, setup records `noted` and continues.
|
|
2083
|
+
3. If the machine public-key fingerprint is already present, setup records
|
|
2084
|
+
`skipped` and does not sign or POST a duplicate.
|
|
2085
|
+
4. Otherwise, the human signing key signs an `EnrollmentGrantRecord` locally.
|
|
2086
|
+
The grant names the machine principal `{ kind: "machine", id: "local" }`,
|
|
2087
|
+
uses the default least-privilege machine scope, and sets `grantedBy` to the
|
|
2088
|
+
human public-key fingerprint.
|
|
2089
|
+
5. `POST /api/enrollments` receives only `{ envelope }`, where `envelope` is the
|
|
2090
|
+
signed DSSE enrollment grant. The machine private key, human private key
|
|
2091
|
+
bytes, key-store values, and private-key paths never enter the request body.
|
|
2092
|
+
HTTP `409` means already registered and becomes `skipped`; other transport or
|
|
2093
|
+
hub failures become `noted` and do not undo local key creation.
|
|
2094
|
+
|
|
2095
|
+
The relay is idempotent (repeating the operation after the first successful
|
|
2096
|
+
registration changes nothing) and the hub is only a storage/relay endpoint. The
|
|
2097
|
+
hub does not create, sign, or endorse the grant.
|
|
2098
|
+
|
|
2099
|
+
## `enrollments` — inspect machine enrollment
|
|
2100
|
+
|
|
2101
|
+
`owenloop enrollments [--hub <url>]` fetches the hub's relayed DSSE envelopes and
|
|
2102
|
+
verifies each entry locally. The command is read-only: it does not call key
|
|
2103
|
+
creation, does not sign a grant, and does not POST to the hub. The command uses
|
|
2104
|
+
the local `allowed_signers` trust root when one is configured.
|
|
2105
|
+
|
|
2106
|
+
The command prints `{ ok, hub, enrollments }` on stdout. Each entry has one of
|
|
2107
|
+
four verdicts:
|
|
2108
|
+
|
|
2109
|
+
| verdict | meaning |
|
|
2110
|
+
|---|---|
|
|
2111
|
+
| `enrolled` | the grant payload and DSSE signature are valid, the signer is in the local `allowed_signers` root, and an enrollment-chain validator approved the grant |
|
|
2112
|
+
| `unenrolled` | no envelope was supplied for the roster entry |
|
|
2113
|
+
| `unverifiable` | verification cannot establish trust, including a missing `allowed_signers` root or the D1 fail-closed state where no chain validator is installed |
|
|
2114
|
+
| `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result is invalid |
|
|
2115
|
+
|
|
2116
|
+
WP-D1 intentionally does not install an enrollment-chain validator. Therefore a
|
|
2117
|
+
well-formed, correctly signed D1 grant is reported as `unverifiable` until WP-D4
|
|
2118
|
+
installs the validator. This prevents a signature from being mistaken for proof
|
|
2119
|
+
that the grantor is enrolled.
|
|
2120
|
+
|
|
2121
|
+
A missing human credential is exit `3`; hub, malformed-response, and other
|
|
2122
|
+
runtime failures are exit `1`; successful classification is exit `0`.
|
|
652
2123
|
|
|
653
2124
|
### Hub resolution differs from `agent new`
|
|
654
2125
|
|
|
@@ -678,8 +2149,8 @@ the flagship command never opens a browser only to fail at the store.)
|
|
|
678
2149
|
### After setup
|
|
679
2150
|
|
|
680
2151
|
If the connected agent account is anything other than `default`, setup prints a
|
|
681
|
-
reminder to run
|
|
682
|
-
right slot.
|
|
2152
|
+
reminder to run `owenloop work` with `OWENLOOP_ACCOUNT=<name>` so the Step Agent
|
|
2153
|
+
reads the right slot.
|
|
683
2154
|
|
|
684
2155
|
**Exit codes.**
|
|
685
2156
|
|
|
@@ -687,7 +2158,7 @@ right slot.
|
|
|
687
2158
|
|---|---|
|
|
688
2159
|
| `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
|
|
689
2160
|
| `1` | setup ran but doctor's core checks did not all pass |
|
|
690
|
-
| non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage
|
|
2161
|
+
| non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage Scoped Identities), a named `--replace-agent` that doesn't exist, or a configured external credential command |
|
|
691
2162
|
|
|
692
2163
|
## `doctor` — check a machine's install
|
|
693
2164
|
|
|
@@ -708,23 +2179,31 @@ The checks, in order:
|
|
|
708
2179
|
| 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
|
|
709
2180
|
| 3 | agent slot | an `agent:<name>` credential is stored | yes |
|
|
710
2181
|
| 4 | agent plane | that agent credential verifies live against the hub | yes |
|
|
711
|
-
| 5 |
|
|
712
|
-
| 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
|
|
2182
|
+
| 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
|
|
2183
|
+
| 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
|
|
2184
|
+
| 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
|
|
2185
|
+
|
|
2186
|
+
The plugin checks also report the detected harness CLI version. An installed
|
|
2187
|
+
plugin whose version cannot be parsed is reported as `version unknown` and is
|
|
2188
|
+
not treated as a failure. A parsed plugin version that differs from the
|
|
2189
|
+
package version is reported as version skew with the remedy `run owenloop
|
|
2190
|
+
setup`. A missing harness reports that the harness is not on `PATH`; a missing
|
|
2191
|
+
plugin reports the harness-specific marketplace and install command.
|
|
713
2192
|
|
|
714
2193
|
Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
|
|
715
2194
|
<origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
|
|
716
|
-
machine with no working human credential still renders
|
|
717
|
-
honestly rather than dropping them.
|
|
2195
|
+
machine with no working human credential still renders the later checks,
|
|
2196
|
+
degrading honestly rather than dropping them.
|
|
718
2197
|
|
|
719
|
-
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise.
|
|
720
|
-
plugin
|
|
721
|
-
marketplace is unpublished.
|
|
2198
|
+
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. Both
|
|
2199
|
+
plugin checks (6–7) are *rendered* but do not affect the exit code.
|
|
722
2200
|
|
|
723
2201
|
## `mcp` — stdio control-plane server for MCP hosts
|
|
724
2202
|
|
|
725
2203
|
`owenloop mcp` is a long-running server that exposes the hub's **human control
|
|
726
|
-
plane** to a local MCP host (Claude Code, or any client that speaks MCP
|
|
727
|
-
stdio).
|
|
2204
|
+
plane** to a local MCP host (Claude Code, Codex, or any client that speaks MCP
|
|
2205
|
+
over stdio). The shipped Claude Code and Codex plugins launch this command from
|
|
2206
|
+
`PATH`. This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
|
|
728
2207
|
subprocess — **you do not run it yourself at a prompt**. It reads
|
|
729
2208
|
newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
|
|
730
2209
|
authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
|
|
@@ -737,34 +2216,84 @@ loopback listener. If no human credential is stored, a tool call returns an
|
|
|
737
2216
|
error telling you to run `owenloop login --hub <origin>` in a terminal and retry
|
|
738
2217
|
(see [Authentication and secrets](#authentication-and-secrets) below).
|
|
739
2218
|
|
|
2219
|
+
### Plugin/CLI version alignment
|
|
2220
|
+
|
|
2221
|
+
The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
|
|
2222
|
+
carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
|
|
2223
|
+
server compares that expected version with its own package version on every
|
|
2224
|
+
recognized `tools/call`. The comparison is strict equality: a mismatch returns
|
|
2225
|
+
a tool error that names both versions and says `Run: owenloop setup`. The
|
|
2226
|
+
server does not reject the MCP startup handshake, so the diagnostic reaches the
|
|
2227
|
+
model and the human instead of appearing only as a transport-closed error.
|
|
2228
|
+
|
|
2229
|
+
Each plugin also declares a `SessionStart` hook. The hook reads the plugin
|
|
2230
|
+
manifest version, sends an MCP `initialize` request to `owenloop mcp` using a
|
|
2231
|
+
non-routable probe origin, and reads `serverInfo.version`; the root CLI has no
|
|
2232
|
+
supported `owenloop --version` flag. The hook reports a missing CLI, an
|
|
2233
|
+
unparseable version, or a mismatch to stderr and always exits successfully, so
|
|
2234
|
+
a diagnostic cannot block session startup. Claude Code runs the hook after
|
|
2235
|
+
installation. Codex runs plugin hooks only after the user approves them in
|
|
2236
|
+
`/hooks`; if the user does not approve Codex hooks, the always-on MCP check
|
|
2237
|
+
still catches a version mismatch when a tool call is made.
|
|
2238
|
+
|
|
2239
|
+
If the versions differ, run `owenloop setup` and follow the printed plugin
|
|
2240
|
+
installation instructions before retrying the MCP tool call.
|
|
2241
|
+
|
|
740
2242
|
### Choosing the hub origin
|
|
741
2243
|
|
|
742
2244
|
`owenloop mcp` binds to exactly one hub origin, resolved in this order:
|
|
743
2245
|
|
|
744
2246
|
1. `--hub <url>` flag.
|
|
745
2247
|
2. `OWENLOOP_HUB` env var.
|
|
746
|
-
3.
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
2248
|
+
3. `~/.owenloop/config.json` — see below.
|
|
2249
|
+
4. If the **file** credential backend holds exactly ONE hub with a valid
|
|
2250
|
+
`human` credential, that hub is used (kept for back-compat with installs
|
|
2251
|
+
from before step 3 existed).
|
|
2252
|
+
5. The built-in **default hub**, `https://api.owenloop.com`.
|
|
2253
|
+
|
|
2254
|
+
Every inference rung after the first two **falls through silently** rather
|
|
2255
|
+
than stopping the server: a missing or corrupt config file, a `hub` value in
|
|
2256
|
+
it that doesn't parse as a valid origin, an unenumerable credential store
|
|
2257
|
+
(macOS Keychain or an external credential command — only the file backend can
|
|
2258
|
+
be listed at all), zero stored hubs, and more than one stored hub all just
|
|
2259
|
+
move on to the next rung. `owenloop mcp` never exits for an inferred-origin
|
|
2260
|
+
reason — this is deliberate: it is a long-running process spawned
|
|
2261
|
+
automatically by an MCP host on every session start, not a one-shot command a
|
|
2262
|
+
human is watching, so a hard stop here would silently break the plugin on any
|
|
2263
|
+
machine using the Keychain backend (the macOS default) unless the operator
|
|
2264
|
+
remembered to set `--hub` or `OWENLOOP_HUB` first.
|
|
2265
|
+
|
|
2266
|
+
The MCP surface is not read-only. It includes `create_agent`, which mints and
|
|
2267
|
+
stores a new agent token, plus state-changing tools such as `create_workflow`,
|
|
2268
|
+
`publish_event`, `submit`, `stage_enrollment`, and the crew mutations. The
|
|
2269
|
+
server still authenticates each tool call against the resolved origin. When no
|
|
2270
|
+
human credential exists at that origin, the first authenticated tool call
|
|
2271
|
+
returns `loginHint` with the origin and asks for `owenloop login --hub
|
|
2272
|
+
<origin>` before the tool-specific action runs. If a credential does exist at
|
|
2273
|
+
an unintended origin and `create_agent` mints there, the stored agent token is
|
|
2274
|
+
revocable; explicit `--hub` and `OWENLOOP_HUB` remain available to avoid
|
|
2275
|
+
inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into-a-slot),
|
|
2276
|
+
which **mints** a new credential directly and therefore stops rather than
|
|
2277
|
+
ever guessing — a wrong guess there is a side effect a retry cannot undo.
|
|
2278
|
+
|
|
2279
|
+
**`~/.owenloop/config.json`** is written by
|
|
2280
|
+
[`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
|
|
2281
|
+
JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
|
|
2282
|
+
recently authenticated against. It exists specifically so `mcp` can learn
|
|
2283
|
+
your hub without enumerating the credential store — see `login`'s own section
|
|
2284
|
+
for exactly when it's written and what happens if the write fails.
|
|
2285
|
+
|
|
2286
|
+
A malformed `--hub`/`OWENLOOP_HUB` value is still a normal exit-`1` error,
|
|
2287
|
+
like every other command — an explicit bad value is reported, never silently
|
|
2288
|
+
skipped, precisely because rungs 1–2 come from something the operator typed
|
|
2289
|
+
or set, not from inference.
|
|
763
2290
|
|
|
764
2291
|
### Tools
|
|
765
2292
|
|
|
766
2293
|
The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
|
|
767
|
-
`create_agent
|
|
2294
|
+
`create_agent`, plus four [crew](#crews) tools (`list_crews`, `create_crew`,
|
|
2295
|
+
`add_crew_member`, `remove_crew_member`) that do not mirror the hub's own MCP
|
|
2296
|
+
toolset. Each baseline tool's result is the hub REST response as one text
|
|
768
2297
|
block; a non-2xx response comes back as an error result.
|
|
769
2298
|
|
|
770
2299
|
| tool | what it does |
|
|
@@ -783,20 +2312,61 @@ block; a non-2xx response comes back as an error result.
|
|
|
783
2312
|
| `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
|
|
784
2313
|
| `publish_event` | publish an event against a contract, starting one run per matched subscription |
|
|
785
2314
|
| `list_subscriptions` | the org's contract subscriptions |
|
|
786
|
-
| `presence_ping` | register/refresh this
|
|
787
|
-
| `
|
|
2315
|
+
| `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 |
|
|
2316
|
+
| `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 |
|
|
788
2317
|
| `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
|
|
789
|
-
| `create_agent` | create a NEW
|
|
790
|
-
|
|
791
|
-
`
|
|
792
|
-
`
|
|
793
|
-
|
|
794
|
-
|
|
2318
|
+
| `create_agent` | create a NEW Scoped Identity and store its credential locally — **never returns the token** |
|
|
2319
|
+
| `list_crews` | list the org's crews, each with its member rows inline — a plain passthrough, no filtering |
|
|
2320
|
+
| `create_crew` | create a crew (`name`, `kind`, optional `ownerMemberId`) |
|
|
2321
|
+
| `add_crew_member` | add a member or agent principal to a crew |
|
|
2322
|
+
| `remove_crew_member` | remove a principal from a crew (tolerant: removing a non-member is a normal result, not an error) |
|
|
2323
|
+
|
|
2324
|
+
`create_agent {name, crews?, scopes?}` mints a fresh Scoped Identity on the hub
|
|
2325
|
+
with `work` scope by default; pass `scopes` (e.g. `["work","run"]`) to choose the
|
|
2326
|
+
minted token's scopes. It then writes the minted `olp_` token straight to this
|
|
2327
|
+
machine's credential store (slot `agent:<name>`). The token is **never** returned in the
|
|
2328
|
+
tool result, printed, or logged — the result is `{name, crews, stored: true}`,
|
|
795
2329
|
built from scratch. It refuses a name that is already taken (the hub's error
|
|
796
2330
|
message is surfaced verbatim; error bodies never carry tokens). If the store
|
|
797
2331
|
write fails, the result says so and tells you to revoke/re-key the agent from
|
|
798
2332
|
the console.
|
|
799
2333
|
|
|
2334
|
+
**The four crew tools** (`list_crews`, `create_crew`, `add_crew_member`,
|
|
2335
|
+
`remove_crew_member`) cover the same four operations as the [`crew` CLI
|
|
2336
|
+
family](#crews) — `crew list`, `crew new`, `crew member add`, `crew member
|
|
2337
|
+
rm` — over the same `/api/*` routes and the same RBAC, but they are not an
|
|
2338
|
+
exact mirror of it: `crew rm` (crew deletion) has no MCP counterpart at all
|
|
2339
|
+
(see below), and where the CLI narrows each hub response into one
|
|
2340
|
+
whitelisted JSON document per invocation (`asPools`, `asPoolCreated`, etc.,
|
|
2341
|
+
so `| jq` always works), these MCP tools are plain passthroughs — the raw
|
|
2342
|
+
hub REST body maps straight to the tool result with no narrowing. Each
|
|
2343
|
+
argument schema deliberately has **no `enum`** on `kind`/`principalKind`,
|
|
2344
|
+
since the hub, not this client, is the enforcement of record for which
|
|
2345
|
+
values are legal.
|
|
2346
|
+
|
|
2347
|
+
Access is **not uniformly admin-only**: `create_crew`, `add_crew_member`, and
|
|
2348
|
+
`remove_crew_member` all carry the same self-service carve-out as their CLI
|
|
2349
|
+
counterparts — a human acting on a **personal crew they own** needs no admin
|
|
2350
|
+
role at all (`assertPoolMutationAllowed`); every other target (a `shared`
|
|
2351
|
+
crew, or a `personal` crew owned by someone else) still requires the admin
|
|
2352
|
+
role. `list_crews` is readable by any of `admin`/`author`/`operator`.
|
|
2353
|
+
`remove_crew_member` is **tolerant**: removing a principal that was never a
|
|
2354
|
+
member is a normal `200` result with `removed: false`, never a tool error.
|
|
2355
|
+
`add_crew_member` is **not** tolerant the same way — adding a principal that
|
|
2356
|
+
is already a member is a hub error, mapped to an `isError` result. Both
|
|
2357
|
+
`add_crew_member` and `remove_crew_member` refuse the org's orphan crew
|
|
2358
|
+
(`orphan:unrouted`) as a `400`, never a `403` — the refusal is
|
|
2359
|
+
identity-independent (it objects to the target crew, not the caller's role),
|
|
2360
|
+
since that crew's membership is derived from the org's current admins and
|
|
2361
|
+
cannot be edited directly.
|
|
2362
|
+
|
|
2363
|
+
**`delete_crew` is deliberately NOT a tool here.** Deleting a crew is a
|
|
2364
|
+
one-way-door operation gated admin-only unconditionally on the hub (unlike
|
|
2365
|
+
the other three verbs, which have the self-service carve-out above), and it
|
|
2366
|
+
was excluded from this MCP surface by design. `owenloop crew rm` on the CLI
|
|
2367
|
+
remains the only way to delete a crew; removing a single **member** (above)
|
|
2368
|
+
is a different, reversible operation and stays in scope for MCP.
|
|
2369
|
+
|
|
800
2370
|
One further tool, `stage_enrollment`, is **conditionally** registered — it
|
|
801
2371
|
appears only when the hub advertises the staging endpoint (or when
|
|
802
2372
|
`OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
|
|
@@ -820,7 +2390,7 @@ interactively.
|
|
|
820
2390
|
|
|
821
2391
|
| variable | effect |
|
|
822
2392
|
|---|---|
|
|
823
|
-
| `OWENLOOP_HUB` |
|
|
2393
|
+
| `OWENLOOP_HUB` | development override for the hub origin (rung 2, above `~/.owenloop/config.json`) |
|
|
824
2394
|
| `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
|
|
825
2395
|
| `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
|
|
826
2396
|
| `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
|
|
@@ -842,7 +2412,7 @@ codebase-advisor pipeline combining collections, a mid-flight human gate,
|
|
|
842
2412
|
per-element knock-backs, and suffixed-reduce fan-ins). Each example's header
|
|
843
2413
|
comment walks through its commands end to end.
|
|
844
2414
|
|
|
845
|
-
Playing every
|
|
2415
|
+
Playing every Step Agent yourself is the fastest way to internalize the loop.
|
|
846
2416
|
Every command prints JSON, so the snippet below pipes through `jq`:
|
|
847
2417
|
|
|
848
2418
|
```sh
|
|
@@ -860,7 +2430,7 @@ owenloop defs # what workflows are available
|
|
|
860
2430
|
wf=$(owenloop create delivery \
|
|
861
2431
|
--provide proposal='{"text":"add dark mode"}' | jq -r .workflow)
|
|
862
2432
|
|
|
863
|
-
# the
|
|
2433
|
+
# the Step Agent loop: tick → run → report
|
|
864
2434
|
run=$(owenloop tick $wf | jq -r '.orders[0].run') # claim the planner job
|
|
865
2435
|
owenloop green $wf $run plan --value '{"plan":"…"}' # report its output
|
|
866
2436
|
|
|
@@ -887,7 +2457,7 @@ instead of waiting for the next tick. `owenloop reap <wf>` runs that same
|
|
|
887
2457
|
cleanup on demand, applying the normal per-step/engine TTL rules — usually a
|
|
888
2458
|
no-op (`{ reaped: 0, details: [] }`). `owenloop reap <wf> --now` is the admin
|
|
889
2459
|
stand-down: it forces every currently-claimed task stale (TTL 0) regardless of
|
|
890
|
-
how fresh its claim is, for reclaiming a
|
|
2460
|
+
how fresh its claim is, for reclaiming a Step Agent you know is dead without
|
|
891
2461
|
waiting out the TTL. Reaping re-arms the task immediately, so **the run that
|
|
892
2462
|
held the cleared lease can no longer commit** — its next `green`/`close` fails
|
|
893
2463
|
with `run <id> no longer holds its lease (reaped or superseded)`, the same
|
|
@@ -927,13 +2497,18 @@ can be born-rejected too — a [judge's](authoring.md#judges--quality-gates-befo
|
|
|
927
2497
|
verdict lands on a stale `submitted` version (a sibling judge already settled
|
|
928
2498
|
it, the producer resubmitted, or a human bypassed it) and the CAS guard
|
|
929
2499
|
refuses it. The result JSON is always written to stdout; the human-readable
|
|
930
|
-
reason goes to stderr. A successful call exits 0 — a
|
|
2500
|
+
reason goes to stderr. A successful call exits 0 — a Step Agent should treat a
|
|
931
2501
|
non-zero exit as a failure, not a success.
|
|
932
2502
|
|
|
933
2503
|
## What a job looks like
|
|
934
2504
|
|
|
935
|
-
`tick` returns `{ workflow, orders, reaped }`. Each order is
|
|
936
|
-
|
|
2505
|
+
`tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
|
|
2506
|
+
packet**: it carries the routing fields and run-time context for the job — the
|
|
2507
|
+
run id, the captured input values, the owed outputs with their reason threads
|
|
2508
|
+
— plus a `defDigest` that names *which definition snapshot* holds the authored
|
|
2509
|
+
instructions. The instructions themselves (the step's `body:` prompt, any
|
|
2510
|
+
`command:` text) are **not** on the order, and `tick`/`order` never print
|
|
2511
|
+
them.
|
|
937
2512
|
|
|
938
2513
|
```jsonc
|
|
939
2514
|
{
|
|
@@ -941,22 +2516,42 @@ a worker needs nothing else to do the work:
|
|
|
941
2516
|
"workflow": "wf_…", // the instance this order belongs to — see deep tick below
|
|
942
2517
|
"step": "builder", // which step this job is for
|
|
943
2518
|
"key": "", // map jobs carry the element key + index
|
|
2519
|
+
"defDigest": "9f2c…", // identifies the definition snapshot to resolve instructions from
|
|
944
2520
|
"inputs": ["plan"],
|
|
945
2521
|
"outputs": ["pr"],
|
|
946
|
-
"
|
|
2522
|
+
"worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
|
|
947
2523
|
"consumes": { "plan": { /* the accepted input value */ } },
|
|
948
2524
|
"owes": [ // the feedback channel
|
|
949
|
-
{ "path": "pr", "
|
|
2525
|
+
{ "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
|
|
950
2526
|
"reasons": [ { "action": "reject", "kind": "judgment", "by": "reviewer",
|
|
951
2527
|
"text": "tests are missing", "at": 0 } ] }
|
|
952
2528
|
]
|
|
953
2529
|
}
|
|
954
2530
|
```
|
|
955
2531
|
|
|
956
|
-
A worker
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
2532
|
+
A worker first **resolves the reference**: the `(defDigest, step, key)`
|
|
2533
|
+
boundary maps the order to the exact authored instructions from the worker's
|
|
2534
|
+
trusted local definition source — the same resolver the embedded engine and
|
|
2535
|
+
the CLI use. Resolution returns the authored `prompt` (with
|
|
2536
|
+
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
|
|
2537
|
+
materialized), the authored `command` if the step has one, and nothing
|
|
2538
|
+
fabricated. If the worker's source does not know the digest — the definition
|
|
2539
|
+
was never delivered, or the current on-disk definition no longer matches the
|
|
2540
|
+
pinned digest — resolution raises `UnknownDefDigestError`. If the digest is
|
|
2541
|
+
known but the referenced step is absent, resolution raises the distinct
|
|
2542
|
+
`UnknownInstructionError` and identifies the digest, step, and key. The worker
|
|
2543
|
+
must refuse either malformed reference rather than guess instructions by step
|
|
2544
|
+
name or fetch unverified text. Once resolved, the worker reads the resolved
|
|
2545
|
+
prompt + `consumes` + `owes`, does the work, reports with `green` (or
|
|
2546
|
+
`emit`/`seal` for collections), then `close`s the job. The reject counts in
|
|
2547
|
+
`owes[]` let a workflow escalate on its own — e.g. switch to a stronger model
|
|
2548
|
+
after two rejections — before the engine stalls the step.
|
|
2549
|
+
|
|
2550
|
+
Static authored text (prompts, commands) travels by digest reference; dynamic
|
|
2551
|
+
data — `consumes` values and the rejection `reasons` threads — stays on the
|
|
2552
|
+
order because it exists only for this run. A remote coordinator or transport
|
|
2553
|
+
that relays these packets never sees authored instruction text and never needs
|
|
2554
|
+
to: instructions resolve at the worker, from a source the worker trusts.
|
|
960
2555
|
|
|
961
2556
|
**Deep tick and `order.workflow`.** `tick <wf>` is **deep by default**: it ticks
|
|
962
2557
|
`<wf>` and then descends into every live `calls:` child, folding their orders
|
|
@@ -969,25 +2564,25 @@ is the earliest wake across all levels. A folded deferral in the deep result
|
|
|
969
2564
|
carries its own `workflow` (absent = the root you ticked, present = a
|
|
970
2565
|
descendant).
|
|
971
2566
|
|
|
972
|
-
**
|
|
973
|
-
which steps this caller claims, but only steps that carry their own `
|
|
974
|
-
are ever excluded: a step is deferred with reason `
|
|
975
|
-
another caller **only** when its `
|
|
976
|
-
the filter you pass. A step with no `
|
|
977
|
-
filtered or not, and a tick that passes no `--
|
|
978
|
-
regardless of
|
|
2567
|
+
**Capability routing (`--capability`).** `tick <wf> --capability <l>` (repeatable) filters
|
|
2568
|
+
which steps this caller claims, but only steps that carry their own `capabilities:`
|
|
2569
|
+
are ever excluded: a step is deferred with reason `capability-mismatch` and left for
|
|
2570
|
+
another caller **only** when its `capabilities:` are non-empty and share no value with
|
|
2571
|
+
the filter you pass. A step with no `capabilities:` is claimed by every caller,
|
|
2572
|
+
filtered or not, and a tick that passes no `--capability` claims every eligible step
|
|
2573
|
+
regardless of capabilities. This is **routing, not
|
|
979
2574
|
authorization**: any caller that can reach the database can tick without a
|
|
980
|
-
filter and claim anything, so
|
|
2575
|
+
filter and claim anything, so capabilities split work across cooperating
|
|
981
2576
|
orchestrators, they never enforce a boundary. See
|
|
982
|
-
[`
|
|
2577
|
+
[`capabilities:`](authoring.md#capabilities--logical-capability-tags) in
|
|
983
2578
|
the authoring guide for the step-side declaration and the starvation hazard to
|
|
984
2579
|
watch for.
|
|
985
2580
|
|
|
986
2581
|
**Child stalls on `status`.** `status <wf>`'s `calls:`-debt entries carry a
|
|
987
2582
|
`child: { workflow, def, done, stalled, debts }` summary once a child has been
|
|
988
2583
|
spawned. `child.stalled: true` means the child (or a grandchild below it) has a
|
|
989
|
-
|
|
990
|
-
on stuck child work. This lets a
|
|
2584
|
+
Step Agent stuck at `maxAttempts` with no green outcome — the parent debt is blocked
|
|
2585
|
+
on stuck child work. This lets a Shift spot a wedged child from the parent
|
|
991
2586
|
`status` alone, without separately walking into the child's own `status`.
|
|
992
2587
|
|
|
993
2588
|
**`wait --until` is single-instance.** `wait <wf> --until eligible|done` polls
|