owenloop 0.5.0 → 0.5.2
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 +67 -0
- package/README.md +144 -35
- package/bin/owenloop.mjs +49 -1
- package/dist/packages/work/src/agent/brief.d.ts +29 -4
- package/dist/packages/work/src/agent/brief.js +49 -4
- package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
- package/dist/packages/work/src/agent/capability-model.js +148 -0
- package/dist/packages/work/src/agent/loop.d.ts +56 -7
- package/dist/packages/work/src/agent/loop.js +166 -9
- package/dist/packages/work/src/bundle/cache.d.ts +7 -5
- package/dist/packages/work/src/bundle/cache.js +20 -6
- package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
- package/dist/packages/work/src/bundle/fetch.js +27 -7
- package/dist/packages/work/src/bundle/types.d.ts +8 -4
- 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/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 +29 -1
- package/dist/packages/work/src/exec/loop.js +313 -35
- 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 +9 -6
- package/dist/packages/work/src/exec/receipt.js +12 -1
- package/dist/packages/work/src/exec/runner.d.ts +7 -1
- package/dist/packages/work/src/exec/runner.js +84 -3
- package/dist/packages/work/src/harness/child-env.js +7 -0
- package/dist/packages/work/src/harness/claude.d.ts +20 -8
- package/dist/packages/work/src/harness/claude.js +260 -58
- package/dist/packages/work/src/harness/codex.d.ts +5 -4
- package/dist/packages/work/src/harness/codex.js +169 -41
- package/dist/packages/work/src/harness/contract.d.ts +36 -11
- package/dist/packages/work/src/harness/fake.js +1 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
- package/dist/packages/work/src/harness/permissions.d.ts +16 -3
- package/dist/packages/work/src/harness/permissions.js +102 -13
- package/dist/packages/work/src/harness/session-store.d.ts +30 -10
- package/dist/packages/work/src/harness/session-store.js +317 -89
- package/dist/packages/work/src/hold/mcp.d.ts +25 -5
- package/dist/packages/work/src/hold/mcp.js +134 -12
- package/dist/packages/work/src/hub/client.d.ts +8 -1
- package/dist/packages/work/src/hub/client.js +15 -1
- package/dist/packages/work/src/hub/types.d.ts +137 -33
- package/dist/packages/work/src/hub/types.js +8 -10
- package/dist/packages/work/src/mcp/server.js +1 -1
- 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 +12 -6
- package/dist/packages/work/src/roles/agent-run.js +115 -34
- package/dist/packages/work/src/roles/exec.d.ts +8 -0
- package/dist/packages/work/src/roles/exec.js +27 -2
- package/dist/packages/work/src/roles/hold.d.ts +6 -0
- package/dist/packages/work/src/roles/hold.js +83 -13
- package/dist/packages/work/src/roles/lint.d.ts +3 -4
- package/dist/packages/work/src/roles/lint.js +41 -7
- package/dist/packages/work/src/roles/settings.js +19 -2
- package/dist/packages/work/src/roles/shift.d.ts +1 -0
- package/dist/packages/work/src/roles/shift.js +36 -2
- package/dist/packages/work/src/settings/settings.d.ts +70 -1
- package/dist/packages/work/src/settings/settings.js +90 -4
- package/dist/packages/work/src/shift/logretention.d.ts +253 -0
- package/dist/packages/work/src/shift/logretention.js +407 -0
- package/dist/packages/work/src/shift/logsink.d.ts +14 -0
- package/dist/packages/work/src/shift/logsink.js +98 -0
- package/dist/packages/work/src/shift/loop.d.ts +32 -4
- package/dist/packages/work/src/shift/loop.js +687 -166
- package/dist/packages/work/src/shift/protocol.d.ts +128 -1
- package/dist/packages/work/src/shift/protocol.js +14 -0
- package/dist/packages/work/src/shift/runtime.d.ts +16 -0
- package/dist/packages/work/src/shift/runtime.js +291 -5
- package/dist/packages/work/src/shift/server.d.ts +13 -0
- package/dist/packages/work/src/shift/server.js +61 -36
- package/dist/packages/work/src/shift/spawn.d.ts +115 -19
- package/dist/packages/work/src/shift/spawn.js +234 -30
- package/dist/packages/work/src/shift/state.d.ts +76 -49
- package/dist/packages/work/src/shift/state.js +350 -103
- package/dist/packages/work/src/shift/truncate.d.ts +35 -0
- package/dist/packages/work/src/shift/truncate.js +73 -0
- package/dist/packages/work/src/submit-proof.d.ts +61 -0
- package/dist/packages/work/src/submit-proof.js +119 -0
- package/dist/packages/work/src/submit-value.d.ts +48 -0
- package/dist/packages/work/src/submit-value.js +118 -0
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +11 -0
- package/dist/src/add.d.ts +64 -259
- package/dist/src/add.js +81 -615
- 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/src/capabilities.d.ts +93 -0
- package/dist/src/capabilities.js +101 -0
- package/dist/src/cli.d.ts +90 -20
- package/dist/src/cli.js +2421 -374
- package/dist/src/credentials.d.ts +4 -3
- package/dist/src/credentials.js +21 -19
- 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 +319 -0
- package/dist/src/crypto/records.js +168 -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/src/defs.d.ts +24 -1
- package/dist/src/defs.js +335 -27
- package/dist/src/engine.d.ts +211 -6
- package/dist/src/engine.js +459 -59
- package/dist/src/factory.d.ts +16 -0
- package/dist/src/factory.js +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/src/hub.d.ts +102 -32
- package/dist/src/hub.js +147 -58
- package/dist/src/index.d.ts +19 -2
- package/dist/src/index.js +23 -2
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +15 -57
- package/dist/src/lock.js +251 -143
- package/dist/src/mcp/serve.d.ts +46 -22
- package/dist/src/mcp/serve.js +174 -44
- package/dist/src/mcp/server.js +12 -1
- package/dist/src/model.d.ts +51 -0
- package/dist/src/model.js +157 -1
- 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/src/paths.d.ts +14 -1
- package/dist/src/paths.js +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1433 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +120 -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/src/store.d.ts +33 -1
- package/dist/src/store.js +57 -4
- package/dist/src/types.d.ts +146 -12
- package/dist/src/untar.d.ts +8 -23
- package/dist/src/untar.js +10 -136
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +64 -6
- package/docs/bundles.md +350 -0
- package/docs/cli.md +1298 -106
- package/docs/crypto.md +832 -0
- package/docs/design.md +342 -20
- package/docs/embedding.md +132 -25
- package/docs/shift-logs.md +642 -0
- package/docs/wire-contracts.md +395 -0
- package/package.json +6 -1
- 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/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,10 +44,17 @@ 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
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) |
|
|
53
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) |
|
|
@@ -58,11 +65,13 @@ for the full breakdown.
|
|
|
58
65
|
| `crew rm <crewId> [--hub <url>]` | delete a crew; work stamped to it moves to the org's orphan crew — see [Crews](#crews) |
|
|
59
66
|
| `crew member add <crewId> <principalKind> <principalId> [--hub <url>]` | add a member or agent to a crew — see [Crews](#crews) |
|
|
60
67
|
| `crew member rm <crewId> <principalId> [--hub <url>]` | remove a principal from a crew — see [Crews](#crews) |
|
|
61
|
-
| `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>]` | onboard this machine: may store human and Scoped Identity credentials, write only execution-settings `hubOrigin`, and
|
|
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) |
|
|
62
70
|
| `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
|
|
63
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) |
|
|
64
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) |
|
|
65
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) |
|
|
66
75
|
| `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
|
|
67
76
|
| `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
|
|
68
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 |
|
|
@@ -83,6 +92,62 @@ for the full breakdown.
|
|
|
83
92
|
| `delete <wf>` | delete an instance and all its rows |
|
|
84
93
|
| `adopt <wf>` | re-pin an instance to the current definition and settle any new debts |
|
|
85
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
|
+
|
|
86
151
|
## `shift` — foreground daemon and client
|
|
87
152
|
|
|
88
153
|
`owenloop shift` is the public local dispatch surface. `shift start` runs the
|
|
@@ -91,6 +156,12 @@ self-driven dispatch loop as a foreground process and listens on
|
|
|
91
156
|
and one JSON-line response. The daemon keeps polling and dispatching while no
|
|
92
157
|
`shift next` client is attached.
|
|
93
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
|
+
|
|
94
165
|
The `shift start` positional argument is a **crew** name. The routing API calls
|
|
95
166
|
that field a **crew**: `serve_crews` contains the selected crew names. Passing
|
|
96
167
|
`--all` maps to an empty `serve_crews` list, which means all crews available to
|
|
@@ -108,7 +179,7 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
|
108
179
|
```text
|
|
109
180
|
owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
|
|
110
181
|
[--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
|
|
111
|
-
[--cache-dir <p>] [--state-dir <p>]
|
|
182
|
+
[--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
|
|
112
183
|
```
|
|
113
184
|
|
|
114
185
|
At least one named crew is required unless `--all` is present. `--all` and
|
|
@@ -128,6 +199,92 @@ one loop sweep and exits instead of keeping the foreground daemon running.
|
|
|
128
199
|
| `--once` | run one loop sweep and exit; without it, keep the daemon in the foreground |
|
|
129
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` |
|
|
130
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
|
+
| `--log-dir <p>` | where `shift.log` and each `<run>.log` are written; precedence is flag, then `OWENLOOP_SHIFT_LOG_DIR`, then `settings.shiftLogDir`, then the resolved state directory |
|
|
203
|
+
| `--log-max-age <ms>` | worker-log retention, swept once at startup; precedence is flag, then `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, then `settings.shiftLogMaxAgeMs`, then `1209600000` (14 days). `0` reaps every completed run's log at the next startup; there is no value that disables the sweep, and `shift.log` is never reaped |
|
|
204
|
+
|
|
205
|
+
**On-disk logs.** A running shift appends its dispatch record to
|
|
206
|
+
`<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
|
|
207
|
+
and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
|
|
208
|
+
process. A log directory that cannot be created costs the logs, never the
|
|
209
|
+
dispatch: the shift reports it once on stderr and serves with logging disabled.
|
|
210
|
+
Full field-by-field contract, retention rules, and uploader notes in
|
|
211
|
+
[`docs/shift-logs.md`](shift-logs.md).
|
|
212
|
+
|
|
213
|
+
**One harness per shift.** A shift has no per-order harness switch and no
|
|
214
|
+
`--harness` flag. It never puts `--harness` on a worker's command line; each
|
|
215
|
+
`agent-run` child resolves its own adapter, in this order:
|
|
216
|
+
|
|
217
|
+
1. its own `--harness` flag — which a shift never supplies;
|
|
218
|
+
2. `OWENLOOP_HARNESS` in the environment the child inherits, which is the
|
|
219
|
+
shift's environment;
|
|
220
|
+
3. the `harness:` field on the verified step definition;
|
|
221
|
+
4. the first registered adapter.
|
|
222
|
+
|
|
223
|
+
Rank 2 is the operator's control. Export `OWENLOOP_HARNESS` in the shell that
|
|
224
|
+
starts the shift and every agent order that shift dispatches runs on that
|
|
225
|
+
adapter. To run two adapters at once, start two shifts:
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
OWENLOOP_HARNESS=claude-code XDG_CONFIG_HOME=~/.config/owenloop-shifts/claude owenloop shift start build --state-dir ~/.local/state/owenloop/claude
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
OWENLOOP_HARNESS=codex XDG_CONFIG_HOME=~/.config/owenloop-shifts/codex owenloop shift start build --state-dir ~/.local/state/owenloop/codex
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Both shifts may serve the SAME crew. The hub does not route by harness — it
|
|
236
|
+
offers an order to any shift whose crew is bound to the order's capability, and
|
|
237
|
+
whichever shift claims it first runs it on its own adapter.
|
|
238
|
+
|
|
239
|
+
**Per-shift `XDG_CONFIG_HOME` is not optional when the adapters differ.** The
|
|
240
|
+
settings file resolves from `XDG_CONFIG_HOME` (see above), and it carries
|
|
241
|
+
`capabilityModels` — a map of composed capability to `{model, effort}` whose
|
|
242
|
+
model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
|
|
243
|
+
adapters need different model ids for the same capability, so they need
|
|
244
|
+
different settings files, so they need different `XDG_CONFIG_HOME` values. A
|
|
245
|
+
shared config directory would give both shifts one adapter's model ids, and the
|
|
246
|
+
shift holding the wrong adapter fails at the vendor API on its first order.
|
|
247
|
+
|
|
248
|
+
Give each shift its own `--state-dir` as well. The state directory holds the
|
|
249
|
+
control socket (`shift.sock`), and a second shift starting against a socket
|
|
250
|
+
another shift already owns is refused.
|
|
251
|
+
|
|
252
|
+
**`capabilityModels` — which model serves which capability.** The hub decides
|
|
253
|
+
WHAT grade of work an order is; it composes the step's capability with the run's
|
|
254
|
+
depth modifier and stamps the result on the order (`builder` at the `deep`
|
|
255
|
+
modifier becomes `builder:deep`). It never decides which model serves that
|
|
256
|
+
grade. That decision is local, and this map is where the operator makes it:
|
|
257
|
+
|
|
258
|
+
```json
|
|
259
|
+
{
|
|
260
|
+
"capabilityModels": {
|
|
261
|
+
"builder:deep": { "model": "claude-opus-5", "effort": "xhigh" },
|
|
262
|
+
"builder": { "model": "claude-sonnet-5", "effort": "high" },
|
|
263
|
+
"wise": { "model": "claude-fable-5", "effort": "xhigh" }
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Lookup runs two passes over the order's capabilities: every EXACT composed key
|
|
269
|
+
first, then every BARE name part. `builder:deep` takes the first row above;
|
|
270
|
+
`builder:express` has no exact row and falls back to the `builder` row.
|
|
271
|
+
`effort` must be one of `low`, `medium`, `high`, `xhigh`, `max`. The model id is
|
|
272
|
+
never checked against a list — owenloop keeps no registry of which models exist,
|
|
273
|
+
so a model released after your owenloop build still works.
|
|
274
|
+
|
|
275
|
+
A capability with no exact row and no bare row is REFUSED, not run on a default:
|
|
276
|
+
the worker releases the claim, reports the refusal to the hub, and exits `1`. An
|
|
277
|
+
order carrying no capabilities at all is not refused — it runs on the adapter's
|
|
278
|
+
own default model, which is how capability-silent steps have always run.
|
|
279
|
+
|
|
280
|
+
**Migrating from `tierMap` / `tierProfiles`.** Both keys are removed. A settings
|
|
281
|
+
file that still contains either one fails to load with an error naming
|
|
282
|
+
`capabilityModels`; the shift does not start. This is deliberate — a shift that
|
|
283
|
+
ignored the old keys would have no capability map at all and would refuse every
|
|
284
|
+
order it claimed, hours later and far from the cause. Rewrite the tier rungs as
|
|
285
|
+
capability rows: whatever `tierProfiles.strongest` pointed at becomes the
|
|
286
|
+
`{model, effort}` of your `:deep` rows, and whatever `standard` pointed at
|
|
287
|
+
becomes the bare rows.
|
|
131
288
|
|
|
132
289
|
A clean start or `--once` completion exits `0`. `owenloop shift --help` also
|
|
133
290
|
exits `0`. Runtime failures such as credential reads or socket/runtime setup
|
|
@@ -137,6 +294,39 @@ hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
|
|
|
137
294
|
daemon's normal lifecycle line is written to stdout when it stays running;
|
|
138
295
|
diagnostics go to stderr.
|
|
139
296
|
|
|
297
|
+
**Dispatch-state safety.** Every current-version direct Shift loop that shares a
|
|
298
|
+
state directory serializes the capacity recheck and durable reservation under
|
|
299
|
+
the same `.dispatch.lock`. The lock is released before process spawn; the per-run
|
|
300
|
+
reservation carries the capacity slot through spawn and PID persistence. Two
|
|
301
|
+
current-version loops therefore cannot both consume the same last slot, and a
|
|
302
|
+
loop that loses the shared-capacity race keeps its already-claimed candidate in
|
|
303
|
+
its local queue. Older Shift loops that predate `.dispatch.lock` do not
|
|
304
|
+
participate in that boundary and must not share the state directory during the
|
|
305
|
+
upgrade. The state directory does not persist one canonical cap: if current-
|
|
306
|
+
version loops sharing the directory are configured with different total or
|
|
307
|
+
agent caps, each loop enforces its own configured limits under the shared lock.
|
|
308
|
+
Use identical cap settings for every loop sharing a state directory.
|
|
309
|
+
|
|
310
|
+
Canonical `*.json` child and reservation records are capacity-bearing state.
|
|
311
|
+
Missing records are benign, including a record that disappears between listing
|
|
312
|
+
and read. A truncated, malformed, or unreadable canonical record is not benign:
|
|
313
|
+
reconciliation fails closed, names the exact path, and disables dispatch until
|
|
314
|
+
an operator repairs the record or removes the record after verifying that no
|
|
315
|
+
child still owns the slot. Owenloop does not skip corrupt records and guess that
|
|
316
|
+
capacity is free. Reconciliation also cancels a reservation when the worker has
|
|
317
|
+
removed its gate after the worker's monotonic two-minute wait, regardless of the
|
|
318
|
+
persisted wall-clock age. A reservation timestamp later than the current wall
|
|
319
|
+
clock is cancelled along with its closed start gate.
|
|
320
|
+
|
|
321
|
+
Persisted reservation age still uses wall time because a monotonic instant cannot
|
|
322
|
+
be reconstructed after a host restart. A smaller backward clock adjustment that
|
|
323
|
+
leaves `reservedAt` in the past can therefore prolong a reservation whose gate
|
|
324
|
+
still exists, such as a parent crash before spawn. The reservation remains
|
|
325
|
+
capacity-bearing until wall time reaches the age limit or an operator verifies
|
|
326
|
+
that no child can start and removes the record and gate. This limitation cannot
|
|
327
|
+
allow provider or command work past the gate: a spawned child independently
|
|
328
|
+
removes the gate and exits after its monotonic two-minute wait.
|
|
329
|
+
|
|
140
330
|
### `shift next [--wait <seconds>]`
|
|
141
331
|
|
|
142
332
|
```text
|
|
@@ -156,14 +346,46 @@ returns promptly when an event is queued, the wait expires, or the shift
|
|
|
156
346
|
explicitly ends. A normal timeout exits `0` and prints the current capacity
|
|
157
347
|
object, for example `{ "cap": 3, "free": 3, "running": 0, "events": [] }`.
|
|
158
348
|
Successful responses use the same capacity shape and may include queued event
|
|
159
|
-
objects.
|
|
160
|
-
|
|
349
|
+
objects.
|
|
350
|
+
|
|
351
|
+
**Every event carries the same three envelope fields**, in addition to whatever
|
|
352
|
+
its own `type` defines:
|
|
353
|
+
|
|
354
|
+
| field | meaning |
|
|
355
|
+
|---|---|
|
|
356
|
+
| `ts` | ISO-8601 UTC with milliseconds, e.g. `2026-08-13T18:04:11.412Z` |
|
|
357
|
+
| `shift` | the shift's human name — `clock_in` can change it between events |
|
|
358
|
+
| `shiftId` | `shf_<uuid>`, the shift process incarnation; stable for the process |
|
|
359
|
+
|
|
360
|
+
The envelope is omitted from the per-type examples below for brevity; it is
|
|
361
|
+
never omitted on the wire. For `dispatched`, `reaped`, and `failed`, `kind` is
|
|
362
|
+
either `exec` or `agent-run`:
|
|
161
363
|
|
|
162
364
|
- `dispatched`: `{ "type": "dispatched", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "pid": 123 }`
|
|
163
365
|
- `reaped`: `{ "type": "reaped", "workflow": "...", "run": "...", "kind": "exec", "pid": 123 }`
|
|
164
366
|
- `failed`: `{ "type": "failed", "workflow": "...", "run": "...", "step": "...", "kind": "exec", "message": "..." }`
|
|
367
|
+
- `bundle-miss`: `{ "type": "bundle-miss", "workflow": "...", "def": "..." }` — a legacy order named a def with no cached bundle, so it was left for hub pickup
|
|
368
|
+
- `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`); display `message`
|
|
165
369
|
- `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
|
|
166
370
|
|
|
371
|
+
Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
|
|
372
|
+
is how they survive the daemon. **Four further record types exist in
|
|
373
|
+
`shift.log` and are never delivered over the socket** — `parked`, `capacity`,
|
|
374
|
+
`hub-error`, and `event-queue-overflow`.
|
|
375
|
+
|
|
376
|
+
An idle `shift next` must block until there is work to report, and each of those
|
|
377
|
+
four would satisfy it with news that no work moved: a startup record, a report
|
|
378
|
+
that the shift is full, a failed call to the hub, or a record about the socket
|
|
379
|
+
queue itself. `parked` and `capacity` are also redundant on the wire — the
|
|
380
|
+
response above already carries live `cap`, `free`, and `running`, which is
|
|
381
|
+
exactly what a `capacity` record restates. `hub-error` is level-triggered at the
|
|
382
|
+
poll interval, so an unreachable hub would otherwise fill the 1000-slot socket
|
|
383
|
+
FIFO and evict the `dispatched`, `failed` and `reaped` records a parked client
|
|
384
|
+
is actually waiting for. In `shift.log`, which is append-only and unbounded, all
|
|
385
|
+
four are load-bearing: they are the only way to tell an idle shift from a
|
|
386
|
+
saturated one, and the only record of every failed hub call. See
|
|
387
|
+
[`docs/shift-logs.md`](shift-logs.md).
|
|
388
|
+
|
|
167
389
|
`gate` is a reserved protocol shape for a future local representation of a
|
|
168
390
|
pending hub gate. Production code does not construct live hub gate events yet;
|
|
169
391
|
the local FIFO test and drill scope are recorded in
|
|
@@ -243,6 +465,87 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
|
243
465
|
| `settings` | print the resolved execution settings file |
|
|
244
466
|
| `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
|
|
245
467
|
|
|
468
|
+
### `work agent-run` — the only Step Agent dispatcher
|
|
469
|
+
|
|
470
|
+
`owenloop work agent-run` is the only supported way to dispatch an agent order.
|
|
471
|
+
The command resolves the verified local workflow definition, applies the final
|
|
472
|
+
`--harness` / environment / step harness selection, and checks every
|
|
473
|
+
`x.harness` restriction before cold start or resume. An unsupported restriction
|
|
474
|
+
starts no provider process, prints each exact refusal, releases the claim, and
|
|
475
|
+
exits `1`.
|
|
476
|
+
|
|
477
|
+
The Codex adapter refuses explicit `filesystem: read-only` and
|
|
478
|
+
`filesystem: workspace-write` before starting or resuming `codex app-server`.
|
|
479
|
+
The refusal is intentional: Codex configuration layers outside the thread
|
|
480
|
+
sandbox prevent the adapter from proving either neutral filesystem boundary.
|
|
481
|
+
Use the Claude Code adapter for the enforceable read-only/Owenloop-only policy,
|
|
482
|
+
or omit `filesystem` / declare `filesystem: unrestricted` only when the workflow
|
|
483
|
+
accepts the corresponding Codex behavior.
|
|
484
|
+
|
|
485
|
+
An absent `x.harness.tools` field preserves the adapter's default tool surface;
|
|
486
|
+
`tools: []` is an explicit empty allow-list. The two forms are not equivalent.
|
|
487
|
+
Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
|
|
488
|
+
`owenloop work lint` runs the same common and adapter checks, but runtime
|
|
489
|
+
preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
|
|
490
|
+
select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
|
|
491
|
+
for the capability matrix and the born-bound Owenloop control-plane exception.
|
|
492
|
+
|
|
493
|
+
**Harness-session durability.** `agent-run` records the provider session in the
|
|
494
|
+
machine-local `sessions.jsonl` log. The `active` row is a safety-critical gate:
|
|
495
|
+
the complete row and its trailing newline are written and fsynced before a
|
|
496
|
+
cold-start adapter may begin provider work or a resumed adapter may deliver new
|
|
497
|
+
feedback. Creating the log also fsyncs the containing directory where the
|
|
498
|
+
platform supports directory fsync. If the active append or fsync fails,
|
|
499
|
+
`agent-run` tears down the provider session, releases the order exactly once,
|
|
500
|
+
skips confirmation, writes no later lifecycle row, and exits with
|
|
501
|
+
`session-store-failed`. Later `turn-ended`, `submitted`, and `dead` rows keep
|
|
502
|
+
ordinary append durability; losing one causes conservative replay or retirement,
|
|
503
|
+
not unrecorded provider work. Compaction fsyncs the replacement before rename
|
|
504
|
+
and fsyncs the directory after rename so a successful compaction preserves a
|
|
505
|
+
previously durable active row.
|
|
506
|
+
|
|
507
|
+
## `trust` — local enrollment trust
|
|
508
|
+
|
|
509
|
+
The `trust` commands create the local enrollment root and signed enrollment
|
|
510
|
+
records. The commands are offline: they do not contact a hub or other remote
|
|
511
|
+
coordinator, and the remote side cannot create, sign, or endorse these records.
|
|
512
|
+
The org root is stored separately from `PrincipalKeyManager` at the injected
|
|
513
|
+
configuration root described in [Signing and key storage](crypto.md#enrollment-chains-attenuation-and-revocation).
|
|
514
|
+
|
|
515
|
+
```text
|
|
516
|
+
owenloop trust init [--force]
|
|
517
|
+
owenloop trust grant --key <pubkey-path> --principal <human|machine|agent>:<id> \
|
|
518
|
+
[--pools a,b|*] [--labels a,b|*] [--namespaces a,b|*] \
|
|
519
|
+
[--delegate no|<n>|unbounded] [--signing-key <path>] [--output <file>]
|
|
520
|
+
owenloop trust revoke --key <SHA256:…> --principal <kind>:<id> \
|
|
521
|
+
[--reason <text>] [--effective-from <epochMs>] \
|
|
522
|
+
[--signing-key <path>] [--output <file>]
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
- `trust init` generates an Ed25519 org-root key pair under the local config
|
|
526
|
+
directory. The containing directory is `0700`, the private key is `0600`,
|
|
527
|
+
and the public key is `0644`. Existing root files are refused unless
|
|
528
|
+
`--force` is supplied. The command prints paths and status, never private key
|
|
529
|
+
bytes.
|
|
530
|
+
- `trust grant` reads an Ed25519 public key from `--key`, assigns it to the
|
|
531
|
+
`--principal`, and signs an `EnrollmentGrantRecord`. Each scope axis defaults
|
|
532
|
+
to an empty array (deny by default); `--delegate` defaults to `no`. The
|
|
533
|
+
signing key defaults to the local org root unless `--signing-key` is given.
|
|
534
|
+
The signed DSSE envelope is written to `--output`, or to the local roster
|
|
535
|
+
directory using a SHA-256 hash of the enrolled key ID as its filename.
|
|
536
|
+
- `trust revoke` signs a `RevocationRecord` for the `SHA256:…` key in `--key`.
|
|
537
|
+
The signing key defaults to the local org root. Without `--effective-from`,
|
|
538
|
+
the cut starts at issuance. With an earlier `--effective-from`, the CLI
|
|
539
|
+
derives `backdated: true`; the flag is never accepted as an independent
|
|
540
|
+
boolean. The signed envelope is written to `--output`, or to the local
|
|
541
|
+
revocations directory using a SHA-256 hash of the revoked key ID.
|
|
542
|
+
|
|
543
|
+
These commands print one JSON result on success. They refuse malformed
|
|
544
|
+
principals, fingerprints, scope lists, delegation values, and timestamps before
|
|
545
|
+
performing the related filesystem or signing work. Trust records are only
|
|
546
|
+
local inputs to the chain validator; transporting a signed envelope is a
|
|
547
|
+
separate concern.
|
|
548
|
+
|
|
246
549
|
## `add` — installing shared workflow defs from GitHub
|
|
247
550
|
|
|
248
551
|
`owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
|
|
@@ -405,8 +708,8 @@ bounded — it only loads folders named by the fail-closed-validated
|
|
|
405
708
|
|
|
406
709
|
- **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
|
|
407
710
|
operator intent to target a literal dir and keeps the pure-scan behavior with
|
|
408
|
-
no fold-in — the rule is "was an override given",
|
|
409
|
-
`OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
|
|
711
|
+
no installed-def or CAS-store fold-in — the rule is "was an override given",
|
|
712
|
+
so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
|
|
410
713
|
Pointing `--defs` straight at an install folder
|
|
411
714
|
(`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
|
|
412
715
|
- **Precedence.** Project-local (top-level) defs win over installed defs; among
|
|
@@ -471,14 +774,501 @@ refuses the whole install (nothing written) on any of these:
|
|
|
471
774
|
buffered into memory (the extraction limits above still re-check the size once
|
|
472
775
|
the bytes are in hand).
|
|
473
776
|
- **Request timeouts.** The sha-resolve fetch times out after 30s and the
|
|
474
|
-
tarball download after 5 min, each surfacing as a friendly error.
|
|
777
|
+
tarball download after 5 min, each surfacing as a friendly error. The
|
|
778
|
+
bundle route applies the same 256 MiB cap and 5 min timeout to its file
|
|
779
|
+
read and URL fetch (see the next section).
|
|
780
|
+
|
|
781
|
+
## `add` with bundles — the content-addressed workflow store
|
|
782
|
+
|
|
783
|
+
`owenloop add <owner>/<repo>[@ref]` (the previous section) installs
|
|
784
|
+
GitHub repos by name into `<defsDir>/<owner>-<repo>-<hash>/`. The **bundle**
|
|
785
|
+
route is a separate, content-addressed installation path for `.wnlp` workflow
|
|
786
|
+
bundles:
|
|
787
|
+
|
|
788
|
+
```text
|
|
789
|
+
owenloop add widget.wnlp # install into the PROJECT store
|
|
790
|
+
owenloop add ./packs/widget.wnlp --global # install into the GLOBAL store
|
|
791
|
+
owenloop add https://example.com/widget.wnlp
|
|
792
|
+
owenloop add --recover [--global] # offline crash recovery (per root)
|
|
793
|
+
```
|
|
794
|
+
|
|
795
|
+
The source is classified before anything else: `owner/repo[@ref]` keeps the
|
|
796
|
+
GitHub route byte-for-byte unchanged; a path ending in `.wnlp` is a bundle
|
|
797
|
+
file; an `http:`/`https:` URL is a bundle URL. Any other URL scheme
|
|
798
|
+
(`ftp:`, `file:`, …) is refused — never a silent fallback. `--global` applies
|
|
799
|
+
only to `.wnlp` bundle sources; a GitHub source with `--global` is refused
|
|
800
|
+
before any network request. The source string is origin data only (diagnostics
|
|
801
|
+
and messages); it is never joined into a filesystem path and never part of a
|
|
802
|
+
bundle's identity. Identity comes from the bundle's own
|
|
803
|
+
`namespace/name@version` coordinate and its canonical content digest.
|
|
804
|
+
|
|
805
|
+
**The `.wnlp` route requires two adapters and fails closed without them.**
|
|
806
|
+
Bundle ingestion (unpacking, manifest integrity, canonical digest,
|
|
807
|
+
coordinate) and pre-commit verification are separate modules with no
|
|
808
|
+
permissive fallback: with either adapter missing, `add` refuses with a named
|
|
809
|
+
error before any staging, journal, or index write. The default CLI binds both
|
|
810
|
+
production adapters. The pre-commit verifier consumes the publication sidecars
|
|
811
|
+
written by `publish` and applies the local `defPolicy` before the object or index
|
|
812
|
+
commit. Hosts that provide both adapters can install real `.wnlp` output from
|
|
813
|
+
`packBundle`; use the `publish` command to create the `.wnlp` bundle plus a
|
|
814
|
+
signed or explicitly unsigned sidecar.
|
|
815
|
+
|
|
816
|
+
### Definition publication policy
|
|
817
|
+
|
|
818
|
+
`defPolicy` is the local execution and installation policy for workflow
|
|
819
|
+
publication signatures. The settings file is
|
|
820
|
+
`$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is non-blank,
|
|
821
|
+
otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
|
|
822
|
+
settings file, write a JSON object such as:
|
|
823
|
+
|
|
824
|
+
```json
|
|
825
|
+
{
|
|
826
|
+
"defPolicy": "enforce"
|
|
827
|
+
}
|
|
828
|
+
```
|
|
829
|
+
|
|
830
|
+
For a one-off CLI invocation, set `OWENLOOP_DEF_POLICY` in the environment, for
|
|
831
|
+
example `OWENLOOP_DEF_POLICY=enforce owenloop add widget.wnlp`. The local
|
|
832
|
+
precedence is explicit host-provided policy, then `OWENLOOP_DEF_POLICY`, then
|
|
833
|
+
the settings file, then the built-in default `warn`. An invalid environment or
|
|
834
|
+
settings-file value fails loudly; it never degrades to `off`.
|
|
835
|
+
|
|
836
|
+
When a host supplies an already-verified organization policy floor through the
|
|
837
|
+
`policyFloor` option seam, the floor is applied **after** that local precedence.
|
|
838
|
+
`unsignedDefs: warn` raises the minimum to `warn`; `unsignedDefs: refuse` raises
|
|
839
|
+
the minimum to `enforce`; the effective policy is the stricter of local policy
|
|
840
|
+
and the floor. **Therefore, local `off` no longer means “no enforcement” when a
|
|
841
|
+
verified org floor is present.** A local operator cannot use `off` to opt out of
|
|
842
|
+
a verified floor. A missing, malformed, unsigned, wrongly signed, or
|
|
843
|
+
under-scoped floor leaves the local policy unchanged.
|
|
844
|
+
|
|
845
|
+
The current CLI and production configuration do not load or verify a floor.
|
|
846
|
+
`policyFloor` is an injection seam only, so this feature is inert until a host
|
|
847
|
+
wires floor loading and verification into that seam.
|
|
848
|
+
|
|
849
|
+
The policy applies at install time and again at execution time. The following
|
|
850
|
+
table describes the local policy result before any verified floor is applied.
|
|
851
|
+
The table uses these verdicts:
|
|
852
|
+
|
|
853
|
+
- `verified` — the publication sidecar verifies against the bundle digest and a
|
|
854
|
+
signer in the local trust root.
|
|
855
|
+
- `unsigned` — the bundle has no publication signature (including an explicit
|
|
856
|
+
`.wnlp.unsigned` sidecar).
|
|
857
|
+
- `unverifiable` — verification could not be completed, such as when the trust
|
|
858
|
+
root is missing or malformed.
|
|
859
|
+
- `invalid` — a present publication signature fails verification, including a
|
|
860
|
+
digest or signer mismatch.
|
|
861
|
+
|
|
862
|
+
| publication verdict | `enforce` | `warn` | `off` |
|
|
863
|
+
|---|---|---|---|
|
|
864
|
+
| `verified` | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. |
|
|
865
|
+
| `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. |
|
|
866
|
+
| `invalid` | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. |
|
|
867
|
+
|
|
868
|
+
**Command-worker hard rule.** A `worker: command` order requires full
|
|
869
|
+
enforcement in every policy value, including `off`: the definition must be
|
|
870
|
+
verified, the enrollment chain must be verified, and the signer scope must be
|
|
871
|
+
checked. `off` does not disable command-worker enforcement. `warn` and `off`
|
|
872
|
+
never allow an unsigned, unverifiable, or invalid definition to reach the
|
|
873
|
+
shell. The command check runs before the policy value is read, and a refusal
|
|
874
|
+
uses the normal `InstructionRefusal` path so the lease stops before command
|
|
875
|
+
execution. A policy floor cannot relax this gate; the gate also fails closed
|
|
876
|
+
regardless of any floor. If an execution host has no publication verifier
|
|
877
|
+
configured, the definition is `unverifiable`; command workers therefore refuse
|
|
878
|
+
rather than treating installed bytes as published trust.
|
|
879
|
+
|
|
880
|
+
### Consume-side artifact policy
|
|
881
|
+
|
|
882
|
+
`artifactPolicy` controls how agent and MCP drivers handle absent evidence and
|
|
883
|
+
missing local prerequisites for signed dynamic artifact values. Supplied but
|
|
884
|
+
invalid evidence always refuses; the policy is a scalar with the same values as
|
|
885
|
+
`defPolicy`: `enforce`, `warn`, or `off`. The precedence is explicit host
|
|
886
|
+
option, then `OWENLOOP_ARTIFACT_POLICY`, then the `artifactPolicy` key in the
|
|
887
|
+
execution settings file, then the built-in default `warn`.
|
|
888
|
+
|
|
889
|
+
For example, the settings file can contain:
|
|
890
|
+
|
|
891
|
+
```json
|
|
892
|
+
{
|
|
893
|
+
"artifactPolicy": "enforce"
|
|
894
|
+
}
|
|
895
|
+
```
|
|
896
|
+
|
|
897
|
+
A one-off invocation can set
|
|
898
|
+
`OWENLOOP_ARTIFACT_POLICY=enforce owenloop work agent-run <order-id>`.
|
|
899
|
+
Invalid values fail loudly; an invalid value never becomes `off`.
|
|
900
|
+
|
|
901
|
+
The consuming driver verifies each delivered value against its serialized DSSE
|
|
902
|
+
submission proof, the signed value digest and version, the locally anchored
|
|
903
|
+
producer enrollment chain, revocations, and any supplied consuming demand's
|
|
904
|
+
scope. A missing proof is not the same as invalid evidence. Dynamic values and
|
|
905
|
+
rejection reasons remain on the wire; the driver verifies those values and
|
|
906
|
+
refuses the whole order on failure rather than dropping only one path.
|
|
907
|
+
|
|
908
|
+
A valid historical proof is not enough to establish the version claimed for the
|
|
909
|
+
current delivery. Ordinary consumed artifacts bind the signed version to the
|
|
910
|
+
claim-time version in `consumedFingerprint`; owed rejection reasons bind to the
|
|
911
|
+
owed claim-time version. If that authoritative expected version is absent, the
|
|
912
|
+
verdict is `unverifiable`, never `verified`, even when the signature, value
|
|
913
|
+
digest, and enrollment chain all verify. The policy table therefore applies
|
|
914
|
+
without a hidden exception: `enforce` refuses that artifact, `warn` warns and
|
|
915
|
+
admits it, and `off` admits it without calling the proof verified. The
|
|
916
|
+
command-worker hard rule below still refuses it under every policy.
|
|
917
|
+
|
|
918
|
+
The current production `exec`, `agent-run`, and `hold` roles do not supply a
|
|
919
|
+
pool, label, or namespace demand. `OrderPacket` has no such demand field to
|
|
920
|
+
derive, so production consume gates enforce the enrollment chain, attenuation,
|
|
921
|
+
and revocation checks but do not apply a demand-dependent `scopePermits`
|
|
922
|
+
restriction. A caller that supplies a demand through the verifier seam gets the
|
|
923
|
+
full scope check. This limitation is a named follow-up.
|
|
924
|
+
|
|
925
|
+
| consumed-evidence verdict | `artifactPolicy=enforce` | `artifactPolicy=warn` | `artifactPolicy=off` |
|
|
926
|
+
|---|---|---|---|
|
|
927
|
+
| `verified` | admit | admit | admit |
|
|
928
|
+
| `absent` | refuse | warn and admit | admit |
|
|
929
|
+
| `unverifiable` | refuse | warn and admit | admit |
|
|
930
|
+
| `invalid` | refuse | refuse | refuse |
|
|
931
|
+
|
|
932
|
+
A refusal is an actionable integrity event. The refusal names the failed link
|
|
933
|
+
and artifact, using names such as `no-proof`, `signature`, `value-digest`,
|
|
934
|
+
`version`, `chain`, `scope`, or `prerequisite`, and includes the workflow, run,
|
|
935
|
+
and step. The driver refuses the whole order; operators must not suppress the
|
|
936
|
+
message or continue with a manually stripped packet.
|
|
937
|
+
|
|
938
|
+
The policy floor's `unsignedArtifacts: warn` value raises the local minimum to
|
|
939
|
+
`artifactPolicy=warn`; `unsignedArtifacts: refuse` raises it to `enforce`. A
|
|
940
|
+
verified floor is merged after local precedence, so local `off` cannot weaken
|
|
941
|
+
the floor.
|
|
942
|
+
|
|
943
|
+
**Command-worker hard rule.** A `worker: command` order refuses `absent`,
|
|
944
|
+
`unverifiable`, and `invalid` consumed evidence regardless of `artifactPolicy`,
|
|
945
|
+
including `off`. The consume-side gate runs before origin or artifact policy
|
|
946
|
+
lookup and before a shell command is built or passed to `/bin/sh -c`. A command
|
|
947
|
+
worker must have a configured consume-side verifier; an unverified dynamic value
|
|
948
|
+
must never reach the shell. Agent prompt rendering and MCP `get_order` likewise
|
|
949
|
+
fail closed when dynamic data exists but no verifier is configured. The driver
|
|
950
|
+
samples the consumer's injected clock once per complete gate invocation; a
|
|
951
|
+
revocation effective at `effectiveFrom <= at` makes a previously consumable
|
|
952
|
+
artifact unconsumable on a later invocation.
|
|
953
|
+
|
|
954
|
+
### Definition origin policy
|
|
955
|
+
|
|
956
|
+
`originRules` is a separate namespace-scoped provenance policy. A signed file
|
|
957
|
+
publication may include `<bundle>.origin.dsse`; installation verifies that
|
|
958
|
+
sidecar against the local `allowed_signers` root and retains the exact bytes at
|
|
959
|
+
`<store-root>/.owenloop/origins/<digest>.dsse`. Execution re-verifies the
|
|
960
|
+
retained evidence against the current trust root. Only a `verified` origin
|
|
961
|
+
verdict is retained. A bundle carrying only `<bundle>.origin.dsse` — with
|
|
962
|
+
neither a publication `.dsse` nor an unsigned marker — is refused at install for
|
|
963
|
+
every origin-policy value, including `off`. `publish` never emits that shape;
|
|
964
|
+
`--unsigned` removes both sidecars. A hub or other remote coordinator may relay
|
|
965
|
+
the sidecar, but never authors or supplies the origin rule.
|
|
966
|
+
|
|
967
|
+
The origin mode uses the same policy values as `defPolicy` — `enforce`, `warn`,
|
|
968
|
+
and `off` — and follows the same scalar precedence: explicit host option,
|
|
969
|
+
`OWENLOOP_ORIGIN_POLICY`, settings-file `originPolicy`, then `warn`. These are
|
|
970
|
+
not trust modes: `Seamless`, `Strict`, and `Paranoid` are a separate axis;
|
|
971
|
+
`Seamless` maps to `warn`, `Strict` maps to `enforce`, and `off` is a local
|
|
972
|
+
operator escape hatch with no trust-mode equivalent. The rule map has no
|
|
973
|
+
environment-variable spelling: explicit host `originRules`, then settings-file
|
|
974
|
+
`originRules`, then an empty map. A namespace with no matching rule has no origin
|
|
975
|
+
requirement. A malformed rule map is a named settings error, not an empty-policy
|
|
976
|
+
fallback.
|
|
977
|
+
|
|
978
|
+
Rules accept exact namespaces (`prod`), namespace prefixes (`prod*`), and
|
|
979
|
+
trailing `/*` sugar (`prod/*`, equivalent to `prod`). `*` and `*/*` are
|
|
980
|
+
catch-all rules. Exact matches beat prefixes; the longest prefix wins; keys
|
|
981
|
+
that normalize to equal specificity, such as `prod` and `prod/*`, are rejected.
|
|
982
|
+
Rule values are minimum provenance strengths, ordered `git` > `console` >
|
|
983
|
+
`agent`; therefore a `console` rule accepts verified `git` and `console`
|
|
984
|
+
origins, and an `agent` rule accepts all three. `any` imposes no requirement.
|
|
985
|
+
|
|
986
|
+
Origin verdicts remain distinct:
|
|
987
|
+
|
|
988
|
+
- `verified` has a strength and is checked against the selected minimum.
|
|
989
|
+
- `absent` means no origin bytes are available. For a signed file publication,
|
|
990
|
+
this means no sidecar was recorded. Unsigned publications and non-file install
|
|
991
|
+
sources also produce `absent`, but those definitions structurally cannot carry
|
|
992
|
+
an origin; those cases must not be described as “no origin was recorded.”
|
|
993
|
+
- `unverifiable` means a prerequisite such as the trust root is unavailable.
|
|
994
|
+
- `invalid` means present origin evidence failed verification and is refused at
|
|
995
|
+
every origin mode, including `off`.
|
|
996
|
+
|
|
997
|
+
For a matched rule, the local origin mode behaves as follows:
|
|
998
|
+
|
|
999
|
+
| origin verdict | `originPolicy=enforce` | `originPolicy=warn` | `originPolicy=off` |
|
|
1000
|
+
|---|---|---|---|
|
|
1001
|
+
| `verified` meeting the minimum | Install and execution succeed. | Install and execution succeed. | Install and execution succeed. |
|
|
1002
|
+
| `verified` weaker than the minimum | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
|
|
1003
|
+
| `absent` or `unverifiable` | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
|
|
1004
|
+
| `invalid` | Install refuses; execution refuses. | Install refuses; execution refuses. | Install refuses; execution refuses. |
|
|
1005
|
+
|
|
1006
|
+
The table applies only when a rule matches. During execution, the driver
|
|
1007
|
+
recovers the namespace by reverse-scanning project and global store indexes for
|
|
1008
|
+
the bundle digest. Equivalent requirements deduplicate. Different requirements
|
|
1009
|
+
produce a named ambiguity refusal. If no coordinate is indexed, `enforce`
|
|
1010
|
+
refuses, `warn` warns, and `off` proceeds. With an empty `originRules` map, the
|
|
1011
|
+
default resolver still invokes the origin verifier once per order, but skips the
|
|
1012
|
+
expensive index reverse-scan; invalid retained origin evidence still refuses.
|
|
1013
|
+
|
|
1014
|
+
A verified policy floor maps `originRules: advisory` to minimum
|
|
1015
|
+
`originPolicy=warn` and `originRules: enforced` to minimum
|
|
1016
|
+
`originPolicy=enforce`. The origin floor is parallel to the publication floor;
|
|
1017
|
+
it does not alter `defPolicy`.
|
|
1018
|
+
|
|
1019
|
+
**Origin policy never relaxes the command-worker hard rule.** A
|
|
1020
|
+
`worker: command` order must pass the publication verification gate first, even
|
|
1021
|
+
when `defPolicy=off`, and only then runs the origin check. Unsigned,
|
|
1022
|
+
unverifiable, or invalid publication evidence never reaches the shell. An
|
|
1023
|
+
origin mode of `off` and every policy-floor preset leave that gate unchanged.
|
|
1024
|
+
|
|
1025
|
+
The local SSHSIG trust root is
|
|
1026
|
+
`$XDG_CONFIG_HOME/owenloop/allowed_signers`, or
|
|
1027
|
+
`$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
|
|
1028
|
+
missing or malformed trust root is `unverifiable`, not `unsigned`.
|
|
1029
|
+
|
|
1030
|
+
### The two store roots
|
|
1031
|
+
|
|
1032
|
+
A store root holds exactly this layout:
|
|
1033
|
+
|
|
1034
|
+
```text
|
|
1035
|
+
<root>/
|
|
1036
|
+
index.json # coordinate → {digest, pinned, workflows?} index
|
|
1037
|
+
objects/
|
|
1038
|
+
sha256/
|
|
1039
|
+
<64-hex-content-digest>/ # one immutable object per digest
|
|
1040
|
+
… # the bundle's files
|
|
1041
|
+
.owenloop/ # per-root lock + crash journal
|
|
1042
|
+
add.lock
|
|
1043
|
+
add.journal
|
|
1044
|
+
.owenloop-staging/ # transient staging (cleared on exit)
|
|
1045
|
+
```
|
|
475
1046
|
|
|
476
|
-
|
|
1047
|
+
- **Project store root** = the resolved defs directory itself (`--defs`,
|
|
1048
|
+
`OWENLOOP_DEFS`, or `./workflows`). The project's pins are reviewable in
|
|
1049
|
+
git there, and the nested `objects/sha256/<digest>/` layout stays below
|
|
1050
|
+
the def loader's scan depth.
|
|
1051
|
+
- **Global store root** = `<home>/.owenloop/workflows`. `--global` selects it;
|
|
1052
|
+
it cannot be combined with `--defs` (the global store has a fixed
|
|
1053
|
+
home-directory location, so an override would only create ambiguity —
|
|
1054
|
+
refused with a clear message). The global root is never used by the
|
|
1055
|
+
GitHub route.
|
|
1056
|
+
|
|
1057
|
+
**Injected home requirement.** `<home>` is the first non-blank value from the
|
|
1058
|
+
caller-injected `HOME` and `USERPROFILE` environment variables (`HOME` wins).
|
|
1059
|
+
The `.wnlp` bundle route uses the same injected home for its default external
|
|
1060
|
+
recovery-marker directory, `<home>/.owenloop/recovery-markers`, even when the
|
|
1061
|
+
bundle targets the project store. If neither variable is supplied, bundle
|
|
1062
|
+
installation refuses before any object or index commit; it never falls back to
|
|
1063
|
+
the process user's ambient home. `add --recover --global` has the same
|
|
1064
|
+
requirement. Project recovery of a v2 fresh-install journal also refuses when
|
|
1065
|
+
its recovery marker requires a home and neither variable is supplied.
|
|
1066
|
+
|
|
1067
|
+
Every object path derives ONLY from its validated digest (lowercase 64-hex).
|
|
1068
|
+
Coordinates, source strings, and version text never join into a path.
|
|
1069
|
+
|
|
1070
|
+
### What an install does, in order
|
|
1071
|
+
|
|
1072
|
+
1. Read the bundle bytes (file or URL) *before* taking the lock — a slow
|
|
1073
|
+
download never holds the project lock. A local `.wnlp` must be a bounded
|
|
1074
|
+
regular file: missing, symlinked, non-regular, or over the 256 MiB cap
|
|
1075
|
+
(checked before *and* after the read) is refused naming the path as
|
|
1076
|
+
given. A URL fetch uses the same 5 min timeout, refuses redirects
|
|
1077
|
+
(`redirect: 'error'`) instead of following them silently, and streams
|
|
1078
|
+
through the same bounded reader.
|
|
1079
|
+
2. Acquire the canonical root lock at `<root>/.owenloop/add.lock`. A GitHub
|
|
1080
|
+
install also retains its legacy cwd-derived lock for compatibility and, when
|
|
1081
|
+
the resolved `--defs` root differs from that cwd, acquires both locks in a
|
|
1082
|
+
fixed order. The canonical lock makes bundle installs from different cwd
|
|
1083
|
+
values serialize when they target one shared `--defs` root; the additional
|
|
1084
|
+
GitHub lock keeps the legacy route compatible.
|
|
1085
|
+
3. Recover a prior interrupted install (before clearing staging — the
|
|
1086
|
+
backups a rollback needs live under the staging root).
|
|
1087
|
+
4. Reread and validate the index **inside** the lock (a corrupt index is a
|
|
1088
|
+
hard error, never a silent reset).
|
|
1089
|
+
5. Ingest via the bundle adapter: unpack into staging, check manifest
|
|
1090
|
+
integrity and runtime compatibility, compute the canonical digest, and
|
|
1091
|
+
extract the full coordinate. The runtime check uses Owenloop's production
|
|
1092
|
+
package version and advertised feature set. A tampered, malformed, or
|
|
1093
|
+
runtime-incompatible bundle stops here — staging debris only, nothing
|
|
1094
|
+
committed.
|
|
1095
|
+
6. Validate the staged tree with the engine's strict pass — the exact bytes
|
|
1096
|
+
that will be committed (parse/lint/validate/bounded `check` + the strict
|
|
1097
|
+
cross-def backstop). For a real `.wnlp`, validation parses `bundle.yaml`
|
|
1098
|
+
through the same runtime-admission boundary and loads every workflow path
|
|
1099
|
+
listed in its `workflows` map; the package manifest itself is not treated as
|
|
1100
|
+
a workflow definition. Any problem refuses the whole install and prints
|
|
1101
|
+
every reason.
|
|
1102
|
+
7. Run the pre-commit verifier (after content validation, before any swap or
|
|
1103
|
+
index write). A rejection commits nothing.
|
|
1104
|
+
8. Write the `applying` crash journal (v2 — its commit-point evidence is the
|
|
1105
|
+
hash of the post-install index bytes).
|
|
1106
|
+
9. Atomically swap the staged object into `objects/sha256/<digest>`
|
|
1107
|
+
(retaining any displaced content on the commit handle), then harden it
|
|
1108
|
+
in place: canonical `0644` files become read-only `0444`, canonical `0755`
|
|
1109
|
+
files become read/execute-only `0555`, and directories become non-writable
|
|
1110
|
+
`0555`. Hardening preserves the executable distinction needed for canonical
|
|
1111
|
+
object reconstruction. Hardening is defense in depth, not the integrity proof
|
|
1112
|
+
— verification reconstructs the complete canonical tar, including
|
|
1113
|
+
`bundle.yaml`, and matches its SHA-256 digest to the object path. A hardening
|
|
1114
|
+
failure rolls the swap back; a partially hardened object is never committed.
|
|
1115
|
+
If the digest's object already exists, the install verifies the existing
|
|
1116
|
+
object through the ingest adapter and commits an index-only change instead
|
|
1117
|
+
(dedupe) — a corrupt or runtime-incompatible existing object is a hard
|
|
1118
|
+
integrity error, never replaced and never fallen through.
|
|
1119
|
+
10. Atomically write `index.json` — the **durable commit point**. Past here
|
|
1120
|
+
a crash rolls forward; before it, everything rolls back. An index-write
|
|
1121
|
+
failure rolls the directory state back and leaves the previous object
|
|
1122
|
+
and index exactly as they were.
|
|
1123
|
+
11. Advance the journal to `finalizing`, discard the retained backup and
|
|
1124
|
+
staging, remove the journal, release the lock.
|
|
1125
|
+
|
|
1126
|
+
On success `add` prints the structured result:
|
|
477
1127
|
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
1128
|
+
```jsonc
|
|
1129
|
+
{
|
|
1130
|
+
"ok": true,
|
|
1131
|
+
"source": "widget.wnlp", // or the URL
|
|
1132
|
+
"level": "project", // or "global"
|
|
1133
|
+
"coordinate": "acme/widget@1.0.0",
|
|
1134
|
+
"digest": "<64-hex>",
|
|
1135
|
+
"workflows": ["delivery", "init"], // every workflow name in the bundle, sorted
|
|
1136
|
+
"objectPath": "<root>/objects/sha256/<64-hex>",
|
|
1137
|
+
"installed": true // false when deduplicated
|
|
1138
|
+
}
|
|
1139
|
+
```
|
|
1140
|
+
|
|
1141
|
+
**Conflict and re-install.** An existing coordinate at a DIFFERENT digest is
|
|
1142
|
+
a conflict error — no implicit retarget; the original digest is retained and
|
|
1143
|
+
nothing is written. An existing coordinate at the SAME digest deduplicates
|
|
1144
|
+
(`installed: false`), verifying the existing object before trusting it.
|
|
1145
|
+
|
|
1146
|
+
**Crash recovery** is the same two-phase discipline as the GitHub route,
|
|
1147
|
+
generalized: the v2 journal's commit-point test compares the hash of the
|
|
1148
|
+
current `index.json` bytes against the journal's recorded metadata hash
|
|
1149
|
+
(route-neutral — no GitHub ledger involved). A fresh v2 install also writes a
|
|
1150
|
+
single-use external recovery marker under the user's recovery-marker directory
|
|
1151
|
+
(default `<home>/.owenloop/recovery-markers`, derived from the injected home
|
|
1152
|
+
described above) before the applying journal. If a crash leaves the destination
|
|
1153
|
+
present with no staging or backup, recovery
|
|
1154
|
+
discards that destination only when the marker exactly matches the store root,
|
|
1155
|
+
destination segments, staging id, and `hadDest: false`; a missing or mismatched
|
|
1156
|
+
marker refuses and preserves the destination and journal. `add --recover --global`
|
|
1157
|
+
runs the store's recovery standalone against the global root with no network
|
|
1158
|
+
and prints `{"ok":true,"recovered":false|true,"outcome":…}` exactly
|
|
1159
|
+
like the project variant. A v1 (GitHub-schema) journal found at the global root
|
|
1160
|
+
is refused fail-closed — there is no ledger there to vouch for it — and a
|
|
1161
|
+
journal recorded against a *different* store root is refused rather than
|
|
1162
|
+
trusting its absolute path. Refusals leave the journal in place as evidence.
|
|
1163
|
+
|
|
1164
|
+
### Resolving what is installed — two separate APIs
|
|
1165
|
+
|
|
1166
|
+
Resolution is deliberately split so execution code cannot accidentally call
|
|
1167
|
+
human-name resolution. Both are library APIs (exported from the package
|
|
1168
|
+
root); every successful resolution verifies the object through the ingest
|
|
1169
|
+
adapter before returning a path — permissions and object shape on disk are
|
|
1170
|
+
defense in depth, not an integrity proof.
|
|
1171
|
+
|
|
1172
|
+
- **Digest resolution (execution).** `resolveWorkflowDigest({digest,
|
|
1173
|
+
projectRoot?, globalRoot, verifier})` — digest only; no index and no
|
|
1174
|
+
workflow name participate. The project object path is tested first when a
|
|
1175
|
+
project root exists; an ABSENT project object may fall through to global,
|
|
1176
|
+
but a PRESENT project object that fails its type probe or verification is
|
|
1177
|
+
a hard integrity error — project tampering is never hidden by falling back
|
|
1178
|
+
to a valid global copy. When both levels hold the same digest, ONE result
|
|
1179
|
+
comes back (level `project`, with presence metadata), not two candidates.
|
|
1180
|
+
Absent at both levels ⇒ `object-missing` integrity error.
|
|
1181
|
+
- **Coordinate resolution (human/CLI).** `resolveWorkflowCoordinate({coordinate,
|
|
1182
|
+
projectRoot?, globalRoot, verifier})` reads BOTH indexes, fail-closed (a
|
|
1183
|
+
corrupt index is a hard error, never silently empty). No entry at either
|
|
1184
|
+
level ⇒ a structured **not-found** error. A project entry wins whenever it
|
|
1185
|
+
exists, even when the global index maps the same coordinate to a different
|
|
1186
|
+
digest; global is the fallback only when project has no match. An index entry
|
|
1187
|
+
whose selected object is missing or corrupt is an integrity error, never a
|
|
1188
|
+
returned path.
|
|
1189
|
+
|
|
1190
|
+
**Calls resolution for installed bundle workflows.** In the default CLI context
|
|
1191
|
+
(no explicit `--defs`/`OWENLOOP_DEFS`), `defs`/`create`/`tick` load CAS workflows
|
|
1192
|
+
from the project and global bundle-store indexes in addition to filesystem defs
|
|
1193
|
+
and the GitHub `add` ledger. A CAS workflow is addressable by the qualified
|
|
1194
|
+
`<package>/<workflow>` name, so a project-local or `add`-installed workflow can
|
|
1195
|
+
call it explicitly. A bare call from a CAS-loaded workflow resolves a sibling
|
|
1196
|
+
from the same bundle digest first; if no sibling has that name, ordinary flat
|
|
1197
|
+
lookup remains available. Bare CAS names are not registered globally, so a
|
|
1198
|
+
workflow in bundle A cannot accidentally call a same-named workflow from bundle
|
|
1199
|
+
B.
|
|
1200
|
+
|
|
1201
|
+
The precedence is explicit: project-local definitions win first, then
|
|
1202
|
+
GitHub-`add` installed definitions, then CAS definitions under qualified keys.
|
|
1203
|
+
Within the CAS layer, exactly one installed bundle holds the unqualified
|
|
1204
|
+
`<package>/<workflow>` name, chosen by two rules in order and never by install
|
|
1205
|
+
order:
|
|
1206
|
+
|
|
1207
|
+
1. **Level.** If any candidate is named by the *project* index, only project
|
|
1208
|
+
candidates compete. A project pin of `pkg@0.1.0` therefore beats a global
|
|
1209
|
+
install of `pkg@0.9.9`. This holds even when the project's own object bytes
|
|
1210
|
+
are missing and were served by exact-digest fallback from the global store —
|
|
1211
|
+
the index that names the object decides, not where the bytes were read.
|
|
1212
|
+
2. **Version.** Among the survivors, the highest canonical SemVer precedence
|
|
1213
|
+
wins (SemVer §11, so `0.1.10` beats `0.1.2` and `1.0.0` beats `1.0.0-rc.1`).
|
|
1214
|
+
|
|
1215
|
+
A canonical SemVer version never loses to a non-SemVer one. If two or more
|
|
1216
|
+
candidates compete and *none* carries a canonical SemVer version, the selection
|
|
1217
|
+
**fails closed**: the unqualified name is left unregistered and a warning names
|
|
1218
|
+
the versions involved, because there is no defined precedence to pick by. Call an
|
|
1219
|
+
exact `<namespace>/<name>@<version>` coordinate in that case. A single
|
|
1220
|
+
non-SemVer version still holds its name — there is nothing to order.
|
|
1221
|
+
|
|
1222
|
+
The refusal warning names only the versions that actually competed. A version
|
|
1223
|
+
dropped by rule 1 is reported separately as never having competed, since it lost
|
|
1224
|
+
on level and was never judged on its version at all. For the same reason,
|
|
1225
|
+
precedence warnings say `project-indexed` / `global-indexed`: precedence follows
|
|
1226
|
+
the index that named the object, whereas a registration's reported level is the
|
|
1227
|
+
store its verified bytes came from, and the two differ under exact-digest
|
|
1228
|
+
fallback.
|
|
1229
|
+
|
|
1230
|
+
Every version that did not win remains reachable under its digest-scoped key, so
|
|
1231
|
+
an already-pinned execution cannot be retargeted, and every exact
|
|
1232
|
+
`<namespace>/<name>@<version>` coordinate always resolves to its own object
|
|
1233
|
+
regardless of which version currently holds the unqualified name.
|
|
1234
|
+
A corrupt CAS index, object, or workflow is skipped with a warning during
|
|
1235
|
+
read-side discovery, so it does not make `status` fail. A running workflow keeps
|
|
1236
|
+
the definition snapshot from its creation (§28), including the CAS bundle
|
|
1237
|
+
provenance used for sibling lookup; installing a newer bundle therefore does not
|
|
1238
|
+
retarget an existing parent instance. The bundle spawn-time pin check compares
|
|
1239
|
+
canonical bundle digests and records a rejected `calls:` debt instead of running
|
|
1240
|
+
a mismatched child.
|
|
1241
|
+
|
|
1242
|
+
Store roots and object directories are probed with `lstat`, never `stat`:
|
|
1243
|
+
a symlink or non-directory squatting at a root, an index path, or an object
|
|
1244
|
+
path is refused outright, and reads never follow a link outside the
|
|
1245
|
+
intended tree.
|
|
1246
|
+
|
|
1247
|
+
**GitHub-route compatibility.** The bundle route changes nothing about
|
|
1248
|
+
`add <owner>/<repo>[@ref]`: the same inputs reach the same parser, the
|
|
1249
|
+
`<owner>-<repo>-<hash>` namespace is untouched, `.owenloop/installed.json`
|
|
1250
|
+
keeps its schema and validation, and an explicit `--defs`/`OWENLOOP_DEFS`
|
|
1251
|
+
still installs through a symlinked defs dir (operator intent). The legacy
|
|
1252
|
+
GitHub repository route installs workflow YAML rather than a format-v2
|
|
1253
|
+
`bundle.yaml`; therefore the GitHub route does not carry or enforce the `.wnlp`
|
|
1254
|
+
runtime compatibility declaration and does not provide the `.wnlp` runtime
|
|
1255
|
+
admission guarantee. Use a `.wnlp` bundle when the publisher must declare a
|
|
1256
|
+
minimum Owenloop version or required runtime features.
|
|
1257
|
+
|
|
1258
|
+
The routes share the canonical resolved-store lock, while the GitHub route
|
|
1259
|
+
retains its legacy cwd-derived lock and journal for compatibility. Recovery
|
|
1260
|
+
checks both journal locations and dispatches by journal version; a v2 store
|
|
1261
|
+
journal uses `index.json` metadata and a v1 GitHub journal uses
|
|
1262
|
+
`installed.json` ledger corroboration.
|
|
1263
|
+
|
|
1264
|
+
## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
|
|
1265
|
+
|
|
1266
|
+
These commands authenticate, publish, and start workflows on a hosted **hub** (default
|
|
1267
|
+
`https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
|
|
1268
|
+
`--hub <url>` → `OWENLOOP_HUB` → the built-in `DEFAULT_HUB`. `connect`, `push`,
|
|
1269
|
+
and `publish` use the safer publishing ladder below and never consult
|
|
1270
|
+
`OWENLOOP_HUB` or guess `DEFAULT_HUB`. They are the only network-bound commands
|
|
1271
|
+
besides `add`, and they talk only to endpoints the hub exposes today — no new
|
|
482
1272
|
service-side surface. The hub URL is normalized to its origin
|
|
483
1273
|
(`scheme://host[:port]`); path/query are dropped. `https` is required for
|
|
484
1274
|
every hub origin except the loopback hosts (`127.0.0.1`, `::1`, `localhost`),
|
|
@@ -492,6 +1282,74 @@ bounce credentials or workflow YAML to another origin (same-origin validation
|
|
|
492
1282
|
covers only the initial URL; a redirect would otherwise re-send the request body
|
|
493
1283
|
cross-origin).
|
|
494
1284
|
|
|
1285
|
+
### The small hosted-workflow path
|
|
1286
|
+
|
|
1287
|
+
Setup is durable. Authenticate and bind the project once, publish or update a
|
|
1288
|
+
definition when its content changes, prepare that published version for the
|
|
1289
|
+
execution account, and keep one crew-scoped Shift running:
|
|
1290
|
+
|
|
1291
|
+
```bash
|
|
1292
|
+
owenloop login --hub https://hub.example
|
|
1293
|
+
owenloop connect --hub https://hub.example
|
|
1294
|
+
owenloop push newhire-onboarding
|
|
1295
|
+
OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
|
|
1296
|
+
OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
|
|
1297
|
+
```
|
|
1298
|
+
|
|
1299
|
+
Starting another run does not repeat installation, publication, preparation,
|
|
1300
|
+
or Shift setup. From the connected project it is one public control-plane
|
|
1301
|
+
command; repeat `--provide name=json` for seeded human inputs:
|
|
1302
|
+
|
|
1303
|
+
```bash
|
|
1304
|
+
owenloop start newhire-onboarding \
|
|
1305
|
+
--crew openai \
|
|
1306
|
+
--provide 'signed_docs={"acknowledged":true}' \
|
|
1307
|
+
--provide 'hardware_choice={"laptop":"MacBook Pro"}'
|
|
1308
|
+
```
|
|
1309
|
+
|
|
1310
|
+
`start` always uses the human credential. The standing Shift uses the
|
|
1311
|
+
`agent:default` credential selected by `--as default`. With no project binding,
|
|
1312
|
+
`start --hub <url>` is accepted explicitly; with neither a binding nor `--hub`,
|
|
1313
|
+
it refuses instead of falling through to `OWENLOOP_HUB` or the production
|
|
1314
|
+
default. If both a binding and `--hub` exist they must agree.
|
|
1315
|
+
|
|
1316
|
+
### `start` — start a published workflow
|
|
1317
|
+
|
|
1318
|
+
`owenloop start <defName>` sends `POST /api/start_run` and prints the new
|
|
1319
|
+
workflow id, its initial status, and the steps whose default crew was stamped or
|
|
1320
|
+
whose capability routes were validated. `--crew <name>` selects the crew for
|
|
1321
|
+
steps that declare no capability; capability-bearing steps continue to use
|
|
1322
|
+
their live hub bindings. `--title <text>` is display-only. Both `--crew` and
|
|
1323
|
+
`--title` require non-empty values; bare flags and `--crew=`/`--title=` are local
|
|
1324
|
+
usage errors before credential or network access. The command does not claim,
|
|
1325
|
+
dispatch, close, or otherwise drive work—the standing Shift discovers the run
|
|
1326
|
+
through its normal crew inbox.
|
|
1327
|
+
|
|
1328
|
+
**Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
|
|
1329
|
+
target in this order:
|
|
1330
|
+
|
|
1331
|
+
1. An explicit `--hub <origin>` always wins.
|
|
1332
|
+
2. `.owenloop/hub.json`, when present, is the project override.
|
|
1333
|
+
3. Global machine state supplies one unambiguous candidate:
|
|
1334
|
+
- with the file credential backend, exactly one origin containing a valid
|
|
1335
|
+
human-slot credential is selected automatically;
|
|
1336
|
+
- Keychain and external-command credential backends cannot enumerate their
|
|
1337
|
+
origins, so the validated `hubOrigin` in
|
|
1338
|
+
`$XDG_CONFIG_HOME/owenloop/settings.json` (or
|
|
1339
|
+
`~/.config/owenloop/settings.json`) is used, and the requested credential
|
|
1340
|
+
slot must exist there before the command proceeds.
|
|
1341
|
+
4. If nothing safe resolves, the command exits 2 without network or publication
|
|
1342
|
+
output effects.
|
|
1343
|
+
|
|
1344
|
+
More than one file-backed origin is also an exit-2 ambiguity: the error lists
|
|
1345
|
+
the origins in deterministic order and asks for `--hub <origin>` or
|
|
1346
|
+
`owenloop connect --hub <origin>`. A non-enumerable backend with no settings
|
|
1347
|
+
`hubOrigin` names the exact settings path and asks for the same explicit
|
|
1348
|
+
choice. `owenloop setup` populates that non-secret settings field. `OWENLOOP_HUB`
|
|
1349
|
+
and `DEFAULT_HUB` are intentionally excluded from the publishing ladder because
|
|
1350
|
+
an ambient guess can target the wrong hub organization; ambiguous or missing
|
|
1351
|
+
resolution fails closed instead of choosing one.
|
|
1352
|
+
|
|
495
1353
|
**Request timeouts.** Every hub call — OAuth discovery, client registration,
|
|
496
1354
|
code exchange, token refresh, `whoami`, the workflow list, and each push — is
|
|
497
1355
|
bounded by a 30s deadline; a stalled hub surfaces as a friendly `hub did not
|
|
@@ -567,28 +1425,66 @@ can read (only read) a stored credential through the same backend logic via the
|
|
|
567
1425
|
package's exported `readStoredCredential` — see
|
|
568
1426
|
[Embedding](embedding.md#whats-exported).
|
|
569
1427
|
|
|
1428
|
+
The macOS `security` adapter treats exit status 44 (`errSecItemNotFound`) as the
|
|
1429
|
+
only absence result: lookup returns no credential, and deletion succeeds
|
|
1430
|
+
idempotently (running the same deletion again changes nothing). Every other
|
|
1431
|
+
numeric status, signal termination, or command-start failure is a fatal backend
|
|
1432
|
+
error. Lookup and logout stop at that error; Owenloop neither reports success
|
|
1433
|
+
nor falls through to or deletes a file-store credential. Mapped errors name only
|
|
1434
|
+
the operation and backend failure class, never the service, account, credential,
|
|
1435
|
+
or stdin command.
|
|
1436
|
+
|
|
570
1437
|
**Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
|
|
571
|
-
token, or a `login`/`logout` that stores or deletes a slot — is serialized by
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
1438
|
+
token, or a `login`/`logout` that stores or deletes a slot — is serialized by the
|
|
1439
|
+
logical `credentials.lock` guard and the persistent SQLite lock database at
|
|
1440
|
+
`credentials.lock.sqlite-v2`, both siblings of `credentials.json` in the config
|
|
1441
|
+
dir (created for the keychain backend too, since the race the lock closes is
|
|
1442
|
+
backend-independent). The concern is a token-refresh
|
|
1443
|
+
race: two owenloop processes hitting an expiring OAuth token at once would each
|
|
1444
|
+
POST a refresh and each persist, and because refresh tokens rotate, the second
|
|
1445
|
+
write clobbers the first with a token whose refresh link is already spent —
|
|
1446
|
+
silently killing the credential. Under the lock a process re-reads the slot
|
|
1447
|
+
after acquiring it and, if another process already refreshed, **adopts** that
|
|
1448
|
+
fresh token instead of refreshing again — one network refresh, one write, no
|
|
1449
|
+
lost token. The lock matters only for OAuth refresh and store/delete; read paths
|
|
1450
|
+
and the external-command mode (which never writes the local store) do not take
|
|
1451
|
+
it.
|
|
1452
|
+
|
|
1453
|
+
SQLite owns exclusion through a `BEGIN IMMEDIATE` transaction tied to the live
|
|
1454
|
+
database connection. Release, normal process exit, and process crash close that
|
|
1455
|
+
connection and release the operating-system lock. Owenloop deliberately keeps
|
|
1456
|
+
the SQLite database path after release; Owenloop never deletes or replaces the
|
|
1457
|
+
path. A sibling `credentials.lock.owner.json` contains only diagnostic process
|
|
1458
|
+
metadata and does not determine ownership. If the lock cannot be acquired within
|
|
1459
|
+
the wait budget, the CLI fails loudly (`another owenloop process is using the
|
|
1460
|
+
credential store … — timed out waiting after Ns`) rather than refreshing
|
|
1461
|
+
unlocked. `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000) and
|
|
1462
|
+
`OWENLOOP_CRED_LOCK_POLL_MS` (default 100) override the wait behavior.
|
|
1463
|
+
`OWENLOOP_CRED_LOCK_STALE_MS` is accepted for compatibility but no longer causes
|
|
1464
|
+
pathname deletion. No token value appears in either lock file or the timeout
|
|
1465
|
+
message.
|
|
1466
|
+
|
|
1467
|
+
**Lock-file upgrade boundary.** The logical lock pathname, such as
|
|
1468
|
+
`credentials.lock`, remains a permanent, parseable JSON compatibility guard.
|
|
1469
|
+
The new SQLite lock database lives at `<logical-lock-path>.sqlite-v2`; for the
|
|
1470
|
+
credential store, that path is `credentials.lock.sqlite-v2`. A new client first
|
|
1471
|
+
holds SQLite's `BEGIN IMMEDIATE` transaction and then installs the guard at the
|
|
1472
|
+
old pathname with an exclusive create. The guard carries an impossible operating-
|
|
1473
|
+
system hostname, so a pre-SQLite client treats the guard as a live foreign-host
|
|
1474
|
+
owner and never age-reclaims it. An already-running old holder can release its
|
|
1475
|
+
ordinary JSON lock normally; the waiting new client then installs the guard and
|
|
1476
|
+
closes the one-way upgrade boundary. Old clients remain blocked after every new-
|
|
1477
|
+
client release or crash, while new clients continue to exclude one another
|
|
1478
|
+
through SQLite.
|
|
1479
|
+
|
|
1480
|
+
Release and crash cleanup close only the SQLite transaction. Owenloop never
|
|
1481
|
+
deletes, renames, or replaces either the permanent guard or the versioned SQLite
|
|
1482
|
+
database during normal lock lifecycle. A corrupt, partial, old-owner, or pre-
|
|
1483
|
+
boundary SQLite file already present at the logical legacy pathname fails closed:
|
|
1484
|
+
stop the relevant processes, verify that no old or pre-boundary process still
|
|
1485
|
+
owns that pathname, remove the legacy pathname manually, and let one upgraded
|
|
1486
|
+
client install the permanent guard. Routine stale-age or PID reclamation is no
|
|
1487
|
+
longer used, and `OWENLOOP_CRED_LOCK_STALE_MS` cannot weaken the boundary.
|
|
592
1488
|
|
|
593
1489
|
**Supplying the credential from your own tooling.** If your secrets live in a
|
|
594
1490
|
secret manager, or you run on a host with no keychain, set
|
|
@@ -630,14 +1526,35 @@ it — a `401` there means the credential is never written to disk. On success
|
|
|
630
1526
|
`orgId`, `identity`, and `email` when the hub returns one), read straight from
|
|
631
1527
|
`whoami`.
|
|
632
1528
|
|
|
1529
|
+
**Recording the hub for `owenloop mcp` (`~/.owenloop/config.json`).** After the
|
|
1530
|
+
credential above is verified and stored, `login` makes one more best-effort
|
|
1531
|
+
write: it records the hub origin it just authenticated against in
|
|
1532
|
+
`~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
|
|
1533
|
+
secret, just the origin). This file is separate from both the credential store
|
|
1534
|
+
above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
|
|
1535
|
+
reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
|
|
1536
|
+
which needs to know your hub without enumerating the credential store (the
|
|
1537
|
+
Keychain and external-command backends can't be listed at all — see below). A
|
|
1538
|
+
failure to write this file is a **warning** printed to stderr, never a fatal
|
|
1539
|
+
error and never blocking `login` itself, since the credential is already
|
|
1540
|
+
safely stored by the time this write is attempted. Logging into a second hub
|
|
1541
|
+
overwrites this file — "last login wins" — so if you routinely switch between
|
|
1542
|
+
hubs, pass `--hub` explicitly to `owenloop mcp` (or set `OWENLOOP_HUB`) rather
|
|
1543
|
+
than relying on whichever `login` ran most recently.
|
|
1544
|
+
|
|
633
1545
|
### `connect` — bind a project to a hub
|
|
634
1546
|
|
|
635
|
-
`owenloop connect`
|
|
636
|
-
|
|
637
|
-
/
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
1547
|
+
`owenloop connect` resolves a target through the publishing ladder, re-verifies
|
|
1548
|
+
the stored credential against `GET /api/whoami`, and writes
|
|
1549
|
+
`.owenloop/hub.json`. Run `login` first. With no `--hub`, an existing binding
|
|
1550
|
+
remains the target; an unbound project uses the unambiguous global fallback.
|
|
1551
|
+
An explicit `--hub` creates or replaces the project override, which is useful
|
|
1552
|
+
for multi-org or multi-hub repositories. `connect` is optional for the ordinary
|
|
1553
|
+
single-hub happy path, not a prerequisite for `push` or `publish`.
|
|
1554
|
+
|
|
1555
|
+
The JSON reports the same org/identity fields as `login`; re-connecting to the
|
|
1556
|
+
**same** origin reports no `switchedFrom`, switching to a **different** hub
|
|
1557
|
+
reports `switchedFrom: <old origin>` and rebinds the project to the new one.
|
|
641
1558
|
|
|
642
1559
|
A symlinked project `.owenloop` directory is refused with a clear error rather
|
|
643
1560
|
than followed: a hostile checkout cannot ship `.owenloop -> /elsewhere` to
|
|
@@ -647,16 +1564,40 @@ guarantee). The same refusal covers the default `state.db` FILE (and its SQLite
|
|
|
647
1564
|
file would otherwise redirect the store's writes, since SQLite follows file
|
|
648
1565
|
symlinks.
|
|
649
1566
|
|
|
650
|
-
### `push` — publish local defs to the
|
|
1567
|
+
### `push` — publish local defs to the resolved hub
|
|
651
1568
|
|
|
652
1569
|
`owenloop push [<defName>...]` publishes the project's workflow defs (all of
|
|
653
|
-
them, or just the named ones) to the hub
|
|
1570
|
+
them, or just the named ones) to the hub selected by the publishing ladder.
|
|
1571
|
+
`--hub` overrides a project binding for that invocation without rewriting it;
|
|
1572
|
+
otherwise the project override wins over global state. An unbound project with
|
|
1573
|
+
one file-backed human credential therefore needs no setup step. Ambiguous or
|
|
1574
|
+
missing candidates exit 2 as described above, and `OWENLOOP_HUB`/
|
|
1575
|
+
`DEFAULT_HUB` never participate. `push` never writes a project binding. It
|
|
654
1576
|
reuses the **exact** all-or-nothing validation gate `add` uses — lint, validate,
|
|
655
1577
|
and a bounded `check` — across every selected def before a single byte is sent;
|
|
656
1578
|
any definite defect aborts the whole push. stdout is machine-parseable JSON;
|
|
657
1579
|
the human-readable diff (`+ new`, `~ changed`, `= unchanged`, `! failed`) goes
|
|
658
1580
|
to stderr.
|
|
659
1581
|
|
|
1582
|
+
`owenloop push --bundle <bundle.wnlp> [<defName>...]` is the executable,
|
|
1583
|
+
bundle-backed form. The exact archive is inspected and becomes the definition
|
|
1584
|
+
source; checkout files are ignored. Push requires exactly one adjacent
|
|
1585
|
+
publication sidecar produced by `owenloop publish` (`.dsse` or `.unsigned`),
|
|
1586
|
+
accepts an optional `.origin.dsse`, uploads those content-addressed objects,
|
|
1587
|
+
then calls `create_workflow` with the archive's canonical digest. This is what
|
|
1588
|
+
makes the hub stamp reference orders with a digest that execution hosts can
|
|
1589
|
+
resolve from their installed bundle store. Because a reference order identifies
|
|
1590
|
+
its executable instructions only by bundle digest plus step name, every workflow
|
|
1591
|
+
definition in the complete archive must use distinct step names. `push --bundle`
|
|
1592
|
+
refuses an archive when two definitions share a step name, even when positional
|
|
1593
|
+
arguments select only one of those definitions; the refusal happens before any
|
|
1594
|
+
bundle, evidence, or workflow-version write. Bundle mode conservatively sends
|
|
1595
|
+
each selected `create_workflow` request even when its YAML hash is unchanged,
|
|
1596
|
+
because the workflow listing does not expose the latest bundle identity; the
|
|
1597
|
+
hub's `(yaml, bundle digest)` idempotency decides whether to version-forward or
|
|
1598
|
+
return `noop`. `--dry-run` validates the archive and sidecars and performs only
|
|
1599
|
+
the read-only server diff—no bundle, sidecar, or definition is uploaded.
|
|
1600
|
+
|
|
660
1601
|
**Idempotency is server-side truth, not a client ledger.** `push` fetches the
|
|
661
1602
|
hub's own view of every def (`GET /api/workflows`, which reports each def's
|
|
662
1603
|
`hash`) and diffs local content against it directly — there is no
|
|
@@ -678,6 +1619,15 @@ batch: the current def is recorded as `failed`, the not-yet-attempted remainder
|
|
|
678
1619
|
is reported under a `skipped` output key, and any `Retry-After` the hub sent is
|
|
679
1620
|
surfaced in the error.
|
|
680
1621
|
|
|
1622
|
+
Selected definitions are published in topological `calls:` order. If a selected
|
|
1623
|
+
dependency fails or is skipped, Owenloop sends no `create_workflow` request for
|
|
1624
|
+
its selected dependents; each dependent is added to `skipped`, names its failed
|
|
1625
|
+
or skipped dependencies in sorted order, and becomes unsuccessful so the skip
|
|
1626
|
+
propagates transitively. Independent selected definitions continue publishing.
|
|
1627
|
+
A locally `unchanged` dependency and a server `noop` dependency both count as
|
|
1628
|
+
successful, so either result permits the dependent to publish. Dependency
|
|
1629
|
+
matching covers bare names and same-package-qualified names in a bundle.
|
|
1630
|
+
|
|
681
1631
|
The def hash is computed by re-parsing the raw YAML with no checkout-specific
|
|
682
1632
|
`baseDir` — the same canonicalization the hub applies — so it's portable
|
|
683
1633
|
across checkouts and machines by construction: a fresh clone at a different
|
|
@@ -698,6 +1648,59 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
|
|
|
698
1648
|
resolve the external file against once the YAML leaves this machine. Inline
|
|
699
1649
|
both before pushing.
|
|
700
1650
|
|
|
1651
|
+
### `publish` — pack and publish a workflow bundle
|
|
1652
|
+
|
|
1653
|
+
```text
|
|
1654
|
+
owenloop publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <origin>]
|
|
1655
|
+
```
|
|
1656
|
+
|
|
1657
|
+
`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.
|
|
1658
|
+
|
|
1659
|
+
The author-key origin comes from the same publishing ladder as `connect` and
|
|
1660
|
+
`push`: `--hub` wins, a project binding overrides global state, one file-backed
|
|
1661
|
+
human origin resolves automatically, and a non-enumerable backend uses the
|
|
1662
|
+
validated execution-settings `hubOrigin` only when the human credential exists.
|
|
1663
|
+
An ambiguous or absent candidate exits 2 before signing, packing, or output
|
|
1664
|
+
writes. `publish` never writes `.owenloop/hub.json`, consults `OWENLOOP_HUB`, or
|
|
1665
|
+
guesses `DEFAULT_HUB`.
|
|
1666
|
+
|
|
1667
|
+
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.
|
|
1668
|
+
|
|
1669
|
+
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.
|
|
1670
|
+
|
|
1671
|
+
`--source` is signer-supplied provenance, not a hub-derived label. The JSON value must be one of these closed forms:
|
|
1672
|
+
|
|
1673
|
+
- `{"kind":"git","repo":"<repo>","commit":"<40- or 64-hex commit SHA>"}`;
|
|
1674
|
+
- `{"kind":"console","user":"<authoring user>"}`, which requires a client-side signing ceremony; or
|
|
1675
|
+
- `{"kind":"agent","agent":"<agent identity>","session":"<session>"}`.
|
|
1676
|
+
|
|
1677
|
+
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.
|
|
1678
|
+
|
|
1679
|
+
`--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:
|
|
1680
|
+
|
|
1681
|
+
- signed mode writes `<output>.wnlp.dsse` and removes a stale `<output>.wnlp.unsigned`;
|
|
1682
|
+
- `--unsigned` writes `<output>.wnlp.unsigned` and removes a stale `<output>.wnlp.dsse`.
|
|
1683
|
+
|
|
1684
|
+
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.
|
|
1685
|
+
|
|
1686
|
+
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.
|
|
1687
|
+
|
|
1688
|
+
Successful invocations print exactly one machine-readable JSON object to stdout. Signed output without an origin has this shape:
|
|
1689
|
+
|
|
1690
|
+
```json
|
|
1691
|
+
{
|
|
1692
|
+
"ok": true,
|
|
1693
|
+
"bundle": "/absolute/path/report-1.2.0.wnlp",
|
|
1694
|
+
"digest": "<64 lowercase hex characters>",
|
|
1695
|
+
"name": "report",
|
|
1696
|
+
"version": "1.2.0",
|
|
1697
|
+
"signed": true,
|
|
1698
|
+
"envelope": "/absolute/path/report-1.2.0.wnlp.dsse"
|
|
1699
|
+
}
|
|
1700
|
+
```
|
|
1701
|
+
|
|
1702
|
+
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.
|
|
1703
|
+
|
|
701
1704
|
Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
|
|
702
1705
|
device-code grant remain recorded follow-ups on the service, not gaps in the
|
|
703
1706
|
CLI.
|
|
@@ -733,10 +1736,22 @@ minting on the wrong org is not undone by a retry:
|
|
|
733
1736
|
|
|
734
1737
|
Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
|
|
735
1738
|
built-in default hub — silently defaulting a mint would risk minting on the
|
|
736
|
-
production hub while you're logged into a dev one.
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
1739
|
+
production hub while you're logged into a dev one. This is deliberately
|
|
1740
|
+
stricter than [`owenloop mcp`'s origin resolution](#choosing-the-hub-origin):
|
|
1741
|
+
`mcp` exposes both reads and writes, including `create_agent` (which mints and
|
|
1742
|
+
stores an agent token), `create_workflow`, `publish_event`, `submit`,
|
|
1743
|
+
`stage_enrollment`, and crew mutations. The default remains acceptable for
|
|
1744
|
+
`mcp` because each tool call authenticates against the resolved origin; when no
|
|
1745
|
+
human credential exists there, the existing `loginHint` surfaces the origin
|
|
1746
|
+
and asks for `owenloop login --hub <origin>` before the tool-specific action
|
|
1747
|
+
runs. If a credential does exist at an unintended origin and `create_agent`
|
|
1748
|
+
mints there, the stored agent token is revocable; `--hub` and `OWENLOOP_HUB`
|
|
1749
|
+
remain available when the operator wants to avoid inference. `agent new`
|
|
1750
|
+
**mints** a new credential directly, a side effect a retry cannot undo, so it
|
|
1751
|
+
stops at step 3 instead of ever guessing. Note that hub enumeration itself is
|
|
1752
|
+
**file-store only**: the keychain and the external-command backend cannot list
|
|
1753
|
+
their entries, so on such a machine step 2 cannot enumerate the store and you
|
|
1754
|
+
must pass `--hub`.
|
|
740
1755
|
|
|
741
1756
|
**`--crews <a,b>`.** A comma-separated list of crew names the token is granted
|
|
742
1757
|
on (trimmed, empties dropped). Omit the flag to let the hub default the token to
|
|
@@ -794,7 +1809,7 @@ allowed) re-reads the route table as it stands at that moment.
|
|
|
794
1809
|
- **Adding.** Running `capability bind` on a capability that is **already bound** ADDS the
|
|
795
1810
|
named crew — it never displaces a crew already bound. Adding widens who can
|
|
796
1811
|
serve the capability, live at the next poll of every in-flight run using it. Re-adding
|
|
797
|
-
a pair that is already there is a normal success, not an error (`
|
|
1812
|
+
a pair that is already there is a normal success, not an error (`alreadyBound:
|
|
798
1813
|
true`).
|
|
799
1814
|
- **Removing.** Running `capability unbind` removes exactly ONE pair. If the capability still
|
|
800
1815
|
has other live routes, it simply routes to a narrower set and nothing pauses.
|
|
@@ -821,9 +1836,9 @@ id; the CLI does no crew lookup and performs no client-side validation of either
|
|
|
821
1836
|
argument (the hub is the enforcement of record).
|
|
822
1837
|
|
|
823
1838
|
**Adding is idempotent per pair.** Re-adding a `(capability, crew)` pair that is
|
|
824
|
-
already bound is a normal success — the hub answers `200` with `
|
|
1839
|
+
already bound is a normal success — the hub answers `200` with `alreadyBound:
|
|
825
1840
|
true` and changes nothing (the original row keeps its creator and timestamp).
|
|
826
|
-
`
|
|
1841
|
+
`boundCrewCount` reports how many **live** crews the capability binds after the write.
|
|
827
1842
|
|
|
828
1843
|
### `capability unbind <capability> <crew>`
|
|
829
1844
|
|
|
@@ -884,7 +1899,7 @@ works. Human progress lines (the two `capability unbind` warnings) go to stderr
|
|
|
884
1899
|
|
|
885
1900
|
| subcommand | stdout |
|
|
886
1901
|
|---|---|
|
|
887
|
-
| `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "
|
|
1902
|
+
| `capability bind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crew": "ml-crew", "alreadyBound": false, "boundCrewCount": 2 }` |
|
|
888
1903
|
| `capability unbind` | `{ "ok": true, "hub": "<origin>", "capability": "gpu", "crewId": "crw_1", "removed": true, "remainingCrewIds": ["crw_2"] }` |
|
|
889
1904
|
| `capability list` | `{ "ok": true, "hub": "<origin>", "routes": [ { "capability": "gpu", "crewId": "crw_1", "crewName": "ml-crew", "createdBy": "u_1", "createdAt": 1738000000000 } ] }` |
|
|
890
1905
|
|
|
@@ -892,9 +1907,9 @@ Every added field carries the **hub's own name**, verbatim — the same words it
|
|
|
892
1907
|
audit log and the web console use — so correlating stdout against them never
|
|
893
1908
|
needs a translation step.
|
|
894
1909
|
|
|
895
|
-
- `
|
|
1910
|
+
- `alreadyBound` (`capability bind`) — was this exact `(capability, crew)` pair already
|
|
896
1911
|
bound before the call? `false` means the pair was created by it.
|
|
897
|
-
- `
|
|
1912
|
+
- `boundCrewCount` (`capability bind`) — how many **live** crews the capability binds
|
|
898
1913
|
after the write. A dangling route routes nothing and is not counted.
|
|
899
1914
|
- `removed` (`capability unbind`) — did this call actually remove a pair? `false` is the
|
|
900
1915
|
tolerant "it was never bound" case, not an error.
|
|
@@ -1062,16 +2077,19 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
|
|
|
1062
2077
|
|
|
1063
2078
|
## `setup` — onboard a machine
|
|
1064
2079
|
|
|
1065
|
-
`owenloop setup` is the one-shot onboarding command. It runs
|
|
2080
|
+
`owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
|
|
1066
2081
|
Depending on the machine state, setup may store the human credential, mint or
|
|
1067
|
-
rekey and store a Scoped Identity credential,
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
2082
|
+
rekey and store a Scoped Identity credential, ensure the three principal
|
|
2083
|
+
signing keys, relay a signed machine enrollment grant, and write only
|
|
2084
|
+
`hubOrigin` in the execution settings file while preserving its other keys.
|
|
2085
|
+
The plugin step probes and, when needed, converges the bundled `owenloop` plugin
|
|
2086
|
+
for each available harness: Claude Code and Codex. Plugin convergence is
|
|
2087
|
+
non-fatal and setup continues when a harness is missing, the bundled marketplace
|
|
2088
|
+
root is unavailable, or a plugin command fails. A second run with the expected
|
|
2089
|
+
plugin version already installed performs no plugin writes. The steps:
|
|
1072
2090
|
|
|
1073
2091
|
1. **inspect** — read-only report of what's already present (human credential,
|
|
1074
|
-
execution settings, `claude` on PATH, agent slots). No writes.
|
|
2092
|
+
execution settings, `claude` and `codex` on PATH, agent slots). No writes.
|
|
1075
2093
|
2. **human login** — verify the stored **human** credential, or run the same
|
|
1076
2094
|
loopback-OAuth browser flow as `owenloop login` when none is present or it no
|
|
1077
2095
|
longer verifies. This is the gate that makes step 3's mint/rekey legal.
|
|
@@ -1079,17 +2097,28 @@ installs the plugin. The steps:
|
|
|
1079
2097
|
hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
|
|
1080
2098
|
(replace the credential of) an existing one. How the target is chosen is
|
|
1081
2099
|
[below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
|
|
1082
|
-
4. **
|
|
2100
|
+
4. **signing keys** — ensure an Ed25519 signing key for each of the three local
|
|
2101
|
+
principals, in order: human, machine, agent. Details
|
|
2102
|
+
[below](#signing-keys-step-4). After key convergence, setup performs the
|
|
2103
|
+
enrollment relay sub-step described below.
|
|
2104
|
+
5. **execution settings** — write only `hubOrigin` into the execution settings
|
|
1083
2105
|
file so the local Step Agent talks to this hub, preserving every other key
|
|
1084
2106
|
(skipped when `hubOrigin` already matches).
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
2107
|
+
6. **plugin** — probe and converge the bundled `owenloop` plugin separately
|
|
2108
|
+
for Claude Code and Codex. When the installed plugin is missing or its
|
|
2109
|
+
version differs from the CLI package, setup adds the bundled marketplace
|
|
2110
|
+
when needed and installs or updates the plugin. Claude Code uses
|
|
2111
|
+
`claude plugin install` for a fresh install and `claude plugin update` for
|
|
2112
|
+
an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
|
|
2113
|
+
fresh installs and upgrades; setup does not call
|
|
2114
|
+
`codex plugin marketplace upgrade`, which applies only to Git marketplaces.
|
|
2115
|
+
**Non-fatal:** a missing harness or failed convergence is reported as
|
|
2116
|
+
`noted` and never fails setup. If the bundled marketplace root is
|
|
2117
|
+
unavailable, setup prints manual commands instead.
|
|
2118
|
+
7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
|
|
1090
2119
|
the same surfaces, whose result becomes setup's exit code.
|
|
1091
2120
|
|
|
1092
|
-
Progress lines (the `[n/
|
|
2121
|
+
Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
1093
2122
|
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
1094
2123
|
**stdout**.
|
|
1095
2124
|
|
|
@@ -1128,6 +2157,88 @@ is a usage error, because rekeying preserves the Scoped Identity's existing scop
|
|
|
1128
2157
|
new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
|
|
1129
2158
|
scopes out with `--scopes work,run`.
|
|
1130
2159
|
|
|
2160
|
+
### Signing keys (step 4)
|
|
2161
|
+
|
|
2162
|
+
Step 4 ensures one Ed25519 signing key per local principal — human, machine,
|
|
2163
|
+
agent — keyed by `{ hub origin, kind, principal id }`. It is **idempotent**:
|
|
2164
|
+
an existing key reports `existing` and is never regenerated or rewritten. A
|
|
2165
|
+
second full setup run performs zero key writes.
|
|
2166
|
+
|
|
2167
|
+
**Storage backends.** The key record goes to the macOS Keychain
|
|
2168
|
+
(`security`), to Linux libsecret (`secret-tool`) when that binary is on
|
|
2169
|
+
`PATH`, and otherwise to a `0600` file under `$HOME/.owenloop/keys/` (both
|
|
2170
|
+
parent directories forced `0700`, symlinks refused). One backend is selected
|
|
2171
|
+
once and a failure is a hard error — there is never a fallback to another
|
|
2172
|
+
backend, because a fallback could mint a second, different key for the same
|
|
2173
|
+
principal. `OWENLOOP_NO_KEYCHAIN=1` forces the file backend. Private bytes
|
|
2174
|
+
never appear on argv or in setup output.
|
|
2175
|
+
|
|
2176
|
+
**`--reuse-ssh-key <path>`** records your own existing Ed25519 SSH key for the
|
|
2177
|
+
**human** principal instead of generating one. The candidate is validated with
|
|
2178
|
+
a non-secret sign/verify challenge before anything is recorded, and only its
|
|
2179
|
+
canonical path + public key are stored — the private key is never copied. It
|
|
2180
|
+
applies to the human key only (machine and agent always get generated keys),
|
|
2181
|
+
and it is a **hard conflict** when a human key already exists: setup keeps the
|
|
2182
|
+
existing key and errors rather than rotating (rotation is not part of this
|
|
2183
|
+
work package). A nonexistent path fails up front, before any browser opens.
|
|
2184
|
+
|
|
2185
|
+
**Secret-output guarantee.** Step 4 prints only `kind state (backend)` — e.g.
|
|
2186
|
+
`✓ signing keys: human created (macos-security), machine created (file), agent
|
|
2187
|
+
existing (macos-security)` — never key bytes, fingerprints, or secret-store
|
|
2188
|
+
values. The full storage and signing model is in
|
|
2189
|
+
[Signing and key storage](crypto.md).
|
|
2190
|
+
|
|
2191
|
+
### Machine enrollment relay
|
|
2192
|
+
|
|
2193
|
+
After the three keys are ensured, setup tries to register the machine public key
|
|
2194
|
+
with the hub. The relay is deliberately subordinate to local key convergence:
|
|
2195
|
+
|
|
2196
|
+
1. Read-only inspect the human signing key. If no human signing key is present,
|
|
2197
|
+
setup records `skipped` and performs no enrollment request.
|
|
2198
|
+
2. `GET /api/enrollments` with the human credential. If the hub is unavailable,
|
|
2199
|
+
returns an unsupported status such as `404`, returns `500`, or returns an
|
|
2200
|
+
unusable response, setup records `noted` and continues.
|
|
2201
|
+
3. If the machine public-key fingerprint is already present, setup records
|
|
2202
|
+
`skipped` and does not sign or POST a duplicate.
|
|
2203
|
+
4. Otherwise, the human signing key signs an `EnrollmentGrantRecord` locally.
|
|
2204
|
+
The grant names the machine principal `{ kind: "machine", id: "local" }`,
|
|
2205
|
+
uses the default least-privilege machine scope, and sets `grantedBy` to the
|
|
2206
|
+
human public-key fingerprint.
|
|
2207
|
+
5. `POST /api/enrollments` receives only `{ envelope }`, where `envelope` is the
|
|
2208
|
+
signed DSSE enrollment grant. The machine private key, human private key
|
|
2209
|
+
bytes, key-store values, and private-key paths never enter the request body.
|
|
2210
|
+
HTTP `409` means already registered and becomes `skipped`; other transport or
|
|
2211
|
+
hub failures become `noted` and do not undo local key creation.
|
|
2212
|
+
|
|
2213
|
+
The relay is idempotent (repeating the operation after the first successful
|
|
2214
|
+
registration changes nothing) and the hub is only a storage/relay endpoint. The
|
|
2215
|
+
hub does not create, sign, or endorse the grant.
|
|
2216
|
+
|
|
2217
|
+
## `enrollments` — inspect machine enrollment
|
|
2218
|
+
|
|
2219
|
+
`owenloop enrollments [--hub <url>]` fetches the hub's relayed DSSE envelopes and
|
|
2220
|
+
verifies each entry locally. The command is read-only: it does not call key
|
|
2221
|
+
creation, does not sign a grant, and does not POST to the hub. The command uses
|
|
2222
|
+
the local `allowed_signers` trust root when one is configured.
|
|
2223
|
+
|
|
2224
|
+
The command prints `{ ok, hub, enrollments }` on stdout. Each entry has one of
|
|
2225
|
+
four verdicts:
|
|
2226
|
+
|
|
2227
|
+
| verdict | meaning |
|
|
2228
|
+
|---|---|
|
|
2229
|
+
| `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 |
|
|
2230
|
+
| `unenrolled` | no envelope was supplied for the roster entry |
|
|
2231
|
+
| `unverifiable` | verification cannot establish trust, including a missing `allowed_signers` root or the D1 fail-closed state where no chain validator is installed |
|
|
2232
|
+
| `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result is invalid |
|
|
2233
|
+
|
|
2234
|
+
WP-D1 intentionally does not install an enrollment-chain validator. Therefore a
|
|
2235
|
+
well-formed, correctly signed D1 grant is reported as `unverifiable` until WP-D4
|
|
2236
|
+
installs the validator. This prevents a signature from being mistaken for proof
|
|
2237
|
+
that the grantor is enrolled.
|
|
2238
|
+
|
|
2239
|
+
A missing human credential is exit `3`; hub, malformed-response, and other
|
|
2240
|
+
runtime failures are exit `1`; successful classification is exit `0`.
|
|
2241
|
+
|
|
1131
2242
|
### Hub resolution differs from `agent new`
|
|
1132
2243
|
|
|
1133
2244
|
`setup` (and `doctor`) resolve the target hub like `agent new` with **one**
|
|
@@ -1187,22 +2298,30 @@ The checks, in order:
|
|
|
1187
2298
|
| 3 | agent slot | an `agent:<name>` credential is stored | yes |
|
|
1188
2299
|
| 4 | agent plane | that agent credential verifies live against the hub | yes |
|
|
1189
2300
|
| 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
|
|
1190
|
-
| 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
|
|
2301
|
+
| 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
|
|
2302
|
+
| 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
|
|
2303
|
+
|
|
2304
|
+
The plugin checks also report the detected harness CLI version. An installed
|
|
2305
|
+
plugin whose version cannot be parsed is reported as `version unknown` and is
|
|
2306
|
+
not treated as a failure. A parsed plugin version that differs from the
|
|
2307
|
+
package version is reported as version skew with the remedy `run owenloop
|
|
2308
|
+
setup`. A missing harness reports that the harness is not on `PATH`; a missing
|
|
2309
|
+
plugin reports the harness-specific marketplace and install command.
|
|
1191
2310
|
|
|
1192
2311
|
Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
|
|
1193
2312
|
<origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
|
|
1194
|
-
machine with no working human credential still renders
|
|
1195
|
-
honestly rather than dropping them.
|
|
2313
|
+
machine with no working human credential still renders the later checks,
|
|
2314
|
+
degrading honestly rather than dropping them.
|
|
1196
2315
|
|
|
1197
|
-
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise.
|
|
1198
|
-
plugin
|
|
1199
|
-
marketplace is unpublished.
|
|
2316
|
+
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. Both
|
|
2317
|
+
plugin checks (6–7) are *rendered* but do not affect the exit code.
|
|
1200
2318
|
|
|
1201
2319
|
## `mcp` — stdio control-plane server for MCP hosts
|
|
1202
2320
|
|
|
1203
2321
|
`owenloop mcp` is a long-running server that exposes the hub's **human control
|
|
1204
|
-
plane** to a local MCP host (Claude Code, or any client that speaks MCP
|
|
1205
|
-
stdio).
|
|
2322
|
+
plane** to a local MCP host (Claude Code, Codex, or any client that speaks MCP
|
|
2323
|
+
over stdio). The shipped Claude Code and Codex plugins launch this command from
|
|
2324
|
+
`PATH`. This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
|
|
1206
2325
|
subprocess — **you do not run it yourself at a prompt**. It reads
|
|
1207
2326
|
newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
|
|
1208
2327
|
authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
|
|
@@ -1215,29 +2334,77 @@ loopback listener. If no human credential is stored, a tool call returns an
|
|
|
1215
2334
|
error telling you to run `owenloop login --hub <origin>` in a terminal and retry
|
|
1216
2335
|
(see [Authentication and secrets](#authentication-and-secrets) below).
|
|
1217
2336
|
|
|
2337
|
+
### Plugin/CLI version alignment
|
|
2338
|
+
|
|
2339
|
+
The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
|
|
2340
|
+
carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
|
|
2341
|
+
server compares that expected version with its own package version on every
|
|
2342
|
+
recognized `tools/call`. The comparison is strict equality: a mismatch returns
|
|
2343
|
+
a tool error that names both versions and says `Run: owenloop setup`. The
|
|
2344
|
+
server does not reject the MCP startup handshake, so the diagnostic reaches the
|
|
2345
|
+
model and the human instead of appearing only as a transport-closed error.
|
|
2346
|
+
|
|
2347
|
+
Each plugin also declares a `SessionStart` hook. The hook reads the plugin
|
|
2348
|
+
manifest version, sends an MCP `initialize` request to `owenloop mcp` using a
|
|
2349
|
+
non-routable probe origin, and reads `serverInfo.version`; the root CLI has no
|
|
2350
|
+
supported `owenloop --version` flag. The hook reports a missing CLI, an
|
|
2351
|
+
unparseable version, or a mismatch to stderr and always exits successfully, so
|
|
2352
|
+
a diagnostic cannot block session startup. Claude Code runs the hook after
|
|
2353
|
+
installation. Codex runs plugin hooks only after the user approves them in
|
|
2354
|
+
`/hooks`; if the user does not approve Codex hooks, the always-on MCP check
|
|
2355
|
+
still catches a version mismatch when a tool call is made.
|
|
2356
|
+
|
|
2357
|
+
If the versions differ, run `owenloop setup` and follow the printed plugin
|
|
2358
|
+
installation instructions before retrying the MCP tool call.
|
|
2359
|
+
|
|
1218
2360
|
### Choosing the hub origin
|
|
1219
2361
|
|
|
1220
2362
|
`owenloop mcp` binds to exactly one hub origin, resolved in this order:
|
|
1221
2363
|
|
|
1222
2364
|
1. `--hub <url>` flag.
|
|
1223
2365
|
2. `OWENLOOP_HUB` env var.
|
|
1224
|
-
3.
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
2366
|
+
3. `~/.owenloop/config.json` — see below.
|
|
2367
|
+
4. If the **file** credential backend holds exactly ONE hub with a valid
|
|
2368
|
+
`human` credential, that hub is used (kept for back-compat with installs
|
|
2369
|
+
from before step 3 existed).
|
|
2370
|
+
5. The built-in **default hub**, `https://api.owenloop.com`.
|
|
2371
|
+
|
|
2372
|
+
Every inference rung after the first two **falls through silently** rather
|
|
2373
|
+
than stopping the server: a missing or corrupt config file, a `hub` value in
|
|
2374
|
+
it that doesn't parse as a valid origin, an unenumerable credential store
|
|
2375
|
+
(macOS Keychain or an external credential command — only the file backend can
|
|
2376
|
+
be listed at all), zero stored hubs, and more than one stored hub all just
|
|
2377
|
+
move on to the next rung. `owenloop mcp` never exits for an inferred-origin
|
|
2378
|
+
reason — this is deliberate: it is a long-running process spawned
|
|
2379
|
+
automatically by an MCP host on every session start, not a one-shot command a
|
|
2380
|
+
human is watching, so a hard stop here would silently break the plugin on any
|
|
2381
|
+
machine using the Keychain backend (the macOS default) unless the operator
|
|
2382
|
+
remembered to set `--hub` or `OWENLOOP_HUB` first.
|
|
2383
|
+
|
|
2384
|
+
The MCP surface is not read-only. It includes `create_agent`, which mints and
|
|
2385
|
+
stores a new agent token, plus state-changing tools such as `create_workflow`,
|
|
2386
|
+
`publish_event`, `submit`, `stage_enrollment`, and the crew mutations. The
|
|
2387
|
+
server still authenticates each tool call against the resolved origin. When no
|
|
2388
|
+
human credential exists at that origin, the first authenticated tool call
|
|
2389
|
+
returns `loginHint` with the origin and asks for `owenloop login --hub
|
|
2390
|
+
<origin>` before the tool-specific action runs. If a credential does exist at
|
|
2391
|
+
an unintended origin and `create_agent` mints there, the stored agent token is
|
|
2392
|
+
revocable; explicit `--hub` and `OWENLOOP_HUB` remain available to avoid
|
|
2393
|
+
inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into-a-slot),
|
|
2394
|
+
which **mints** a new credential directly and therefore stops rather than
|
|
2395
|
+
ever guessing — a wrong guess there is a side effect a retry cannot undo.
|
|
2396
|
+
|
|
2397
|
+
**`~/.owenloop/config.json`** is written by
|
|
2398
|
+
[`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
|
|
2399
|
+
JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
|
|
2400
|
+
recently authenticated against. It exists specifically so `mcp` can learn
|
|
2401
|
+
your hub without enumerating the credential store — see `login`'s own section
|
|
2402
|
+
for exactly when it's written and what happens if the write fails.
|
|
2403
|
+
|
|
2404
|
+
A malformed `--hub`/`OWENLOOP_HUB` value is still a normal exit-`1` error,
|
|
2405
|
+
like every other command — an explicit bad value is reported, never silently
|
|
2406
|
+
skipped, precisely because rungs 1–2 come from something the operator typed
|
|
2407
|
+
or set, not from inference.
|
|
1241
2408
|
|
|
1242
2409
|
### Tools
|
|
1243
2410
|
|
|
@@ -1341,7 +2508,7 @@ interactively.
|
|
|
1341
2508
|
|
|
1342
2509
|
| variable | effect |
|
|
1343
2510
|
|---|---|
|
|
1344
|
-
| `OWENLOOP_HUB` |
|
|
2511
|
+
| `OWENLOOP_HUB` | development override for the hub origin (rung 2, above `~/.owenloop/config.json`) |
|
|
1345
2512
|
| `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
|
|
1346
2513
|
| `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
|
|
1347
2514
|
| `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
|
|
@@ -1453,8 +2620,13 @@ non-zero exit as a failure, not a success.
|
|
|
1453
2620
|
|
|
1454
2621
|
## What a job looks like
|
|
1455
2622
|
|
|
1456
|
-
`tick` returns `{ workflow, orders, reaped }`. Each order is
|
|
1457
|
-
|
|
2623
|
+
`tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
|
|
2624
|
+
packet**: it carries the routing fields and run-time context for the job — the
|
|
2625
|
+
run id, the captured input values, the owed outputs with their reason threads
|
|
2626
|
+
— plus a `defDigest` that names *which definition snapshot* holds the authored
|
|
2627
|
+
instructions. The instructions themselves (the step's `body:` prompt, any
|
|
2628
|
+
`command:` text) are **not** on the order, and `tick`/`order` never print
|
|
2629
|
+
them.
|
|
1458
2630
|
|
|
1459
2631
|
```jsonc
|
|
1460
2632
|
{
|
|
@@ -1462,22 +2634,42 @@ a Step Agent needs nothing else to do the work:
|
|
|
1462
2634
|
"workflow": "wf_…", // the instance this order belongs to — see deep tick below
|
|
1463
2635
|
"step": "builder", // which step this job is for
|
|
1464
2636
|
"key": "", // map jobs carry the element key + index
|
|
2637
|
+
"defDigest": "9f2c…", // identifies the definition snapshot to resolve instructions from
|
|
1465
2638
|
"inputs": ["plan"],
|
|
1466
2639
|
"outputs": ["pr"],
|
|
1467
|
-
"
|
|
2640
|
+
"worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
|
|
1468
2641
|
"consumes": { "plan": { /* the accepted input value */ } },
|
|
1469
2642
|
"owes": [ // the feedback channel
|
|
1470
|
-
{ "path": "pr", "
|
|
2643
|
+
{ "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
|
|
1471
2644
|
"reasons": [ { "action": "reject", "kind": "judgment", "by": "reviewer",
|
|
1472
2645
|
"text": "tests are missing", "at": 0 } ] }
|
|
1473
2646
|
]
|
|
1474
2647
|
}
|
|
1475
2648
|
```
|
|
1476
2649
|
|
|
1477
|
-
A
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
2650
|
+
A worker first **resolves the reference**: the `(defDigest, step, key)`
|
|
2651
|
+
boundary maps the order to the exact authored instructions from the worker's
|
|
2652
|
+
trusted local definition source — the same resolver the embedded engine and
|
|
2653
|
+
the CLI use. Resolution returns the authored `prompt` (with
|
|
2654
|
+
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
|
|
2655
|
+
materialized), the authored `command` if the step has one, and nothing
|
|
2656
|
+
fabricated. If the worker's source does not know the digest — the definition
|
|
2657
|
+
was never delivered, or the current on-disk definition no longer matches the
|
|
2658
|
+
pinned digest — resolution raises `UnknownDefDigestError`. If the digest is
|
|
2659
|
+
known but the referenced step is absent, resolution raises the distinct
|
|
2660
|
+
`UnknownInstructionError` and identifies the digest, step, and key. The worker
|
|
2661
|
+
must refuse either malformed reference rather than guess instructions by step
|
|
2662
|
+
name or fetch unverified text. Once resolved, the worker reads the resolved
|
|
2663
|
+
prompt + `consumes` + `owes`, does the work, reports with `green` (or
|
|
2664
|
+
`emit`/`seal` for collections), then `close`s the job. The reject counts in
|
|
2665
|
+
`owes[]` let a workflow escalate on its own — e.g. switch to a stronger model
|
|
2666
|
+
after two rejections — before the engine stalls the step.
|
|
2667
|
+
|
|
2668
|
+
Static authored text (prompts, commands) travels by digest reference; dynamic
|
|
2669
|
+
data — `consumes` values and the rejection `reasons` threads — stays on the
|
|
2670
|
+
order because it exists only for this run. A remote coordinator or transport
|
|
2671
|
+
that relays these packets never sees authored instruction text and never needs
|
|
2672
|
+
to: instructions resolve at the worker, from a source the worker trusts.
|
|
1481
2673
|
|
|
1482
2674
|
**Deep tick and `order.workflow`.** `tick <wf>` is **deep by default**: it ticks
|
|
1483
2675
|
`<wf>` and then descends into every live `calls:` child, folding their orders
|