owenloop 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +45 -0
- package/README.md +137 -35
- package/bin/owenloop.mjs +49 -1
- package/dist/packages/work/src/agent/brief.d.ts +8 -4
- package/dist/packages/work/src/agent/brief.js +7 -3
- package/dist/packages/work/src/agent/loop.d.ts +13 -7
- package/dist/packages/work/src/agent/loop.js +136 -9
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/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 +12 -1
- package/dist/packages/work/src/exec/loop.js +137 -20
- 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 +74 -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 +27 -9
- package/dist/packages/work/src/harness/session-store.js +271 -67
- package/dist/packages/work/src/hold/mcp.d.ts +25 -5
- package/dist/packages/work/src/hold/mcp.js +126 -11
- package/dist/packages/work/src/hub/client.d.ts +2 -1
- package/dist/packages/work/src/hub/client.js +14 -1
- package/dist/packages/work/src/hub/types.d.ts +69 -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 +116 -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 +4 -0
- package/dist/packages/work/src/roles/hold.js +44 -5
- 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 +5 -0
- package/dist/packages/work/src/roles/shift.d.ts +1 -0
- package/dist/packages/work/src/roles/shift.js +23 -1
- package/dist/packages/work/src/settings/settings.d.ts +17 -1
- package/dist/packages/work/src/settings/settings.js +39 -0
- package/dist/packages/work/src/shift/loop.d.ts +14 -3
- package/dist/packages/work/src/shift/loop.js +447 -164
- package/dist/packages/work/src/shift/protocol.d.ts +4 -0
- package/dist/packages/work/src/shift/runtime.d.ts +2 -0
- package/dist/packages/work/src/shift/runtime.js +66 -3
- package/dist/packages/work/src/shift/spawn.d.ts +41 -18
- package/dist/packages/work/src/shift/spawn.js +89 -31
- package/dist/packages/work/src/shift/state.d.ts +53 -51
- package/dist/packages/work/src/shift/state.js +325 -102
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -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/cli.d.ts +90 -20
- package/dist/src/cli.js +2407 -365
- 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 +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/src/defs.d.ts +24 -1
- package/dist/src/defs.js +145 -25
- package/dist/src/engine.d.ts +99 -3
- package/dist/src/engine.js +238 -34
- 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 +75 -21
- package/dist/src/hub.js +123 -40
- package/dist/src/index.d.ts +17 -2
- package/dist/src/index.js +20 -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 +167 -44
- package/dist/src/mcp/server.js +12 -1
- package/dist/src/model.d.ts +15 -0
- package/dist/src/model.js +111 -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 +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/src/types.d.ts +45 -11
- 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 +57 -6
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1171 -97
- package/docs/crypto.md +816 -0
- package/docs/design.md +342 -20
- package/docs/embedding.md +132 -25
- package/docs/wire-contracts.md +380 -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
|
|
@@ -137,6 +208,39 @@ hub origin, or a missing Scoped Identity credential — exit `2`. The foreground
|
|
|
137
208
|
daemon's normal lifecycle line is written to stdout when it stays running;
|
|
138
209
|
diagnostics go to stderr.
|
|
139
210
|
|
|
211
|
+
**Dispatch-state safety.** Every current-version direct Shift loop that shares a
|
|
212
|
+
state directory serializes the capacity recheck and durable reservation under
|
|
213
|
+
the same `.dispatch.lock`. The lock is released before process spawn; the per-run
|
|
214
|
+
reservation carries the capacity slot through spawn and PID persistence. Two
|
|
215
|
+
current-version loops therefore cannot both consume the same last slot, and a
|
|
216
|
+
loop that loses the shared-capacity race keeps its already-claimed candidate in
|
|
217
|
+
its local queue. Older Shift loops that predate `.dispatch.lock` do not
|
|
218
|
+
participate in that boundary and must not share the state directory during the
|
|
219
|
+
upgrade. The state directory does not persist one canonical cap: if current-
|
|
220
|
+
version loops sharing the directory are configured with different total or
|
|
221
|
+
agent caps, each loop enforces its own configured limits under the shared lock.
|
|
222
|
+
Use identical cap settings for every loop sharing a state directory.
|
|
223
|
+
|
|
224
|
+
Canonical `*.json` child and reservation records are capacity-bearing state.
|
|
225
|
+
Missing records are benign, including a record that disappears between listing
|
|
226
|
+
and read. A truncated, malformed, or unreadable canonical record is not benign:
|
|
227
|
+
reconciliation fails closed, names the exact path, and disables dispatch until
|
|
228
|
+
an operator repairs the record or removes the record after verifying that no
|
|
229
|
+
child still owns the slot. Owenloop does not skip corrupt records and guess that
|
|
230
|
+
capacity is free. Reconciliation also cancels a reservation when the worker has
|
|
231
|
+
removed its gate after the worker's monotonic two-minute wait, regardless of the
|
|
232
|
+
persisted wall-clock age. A reservation timestamp later than the current wall
|
|
233
|
+
clock is cancelled along with its closed start gate.
|
|
234
|
+
|
|
235
|
+
Persisted reservation age still uses wall time because a monotonic instant cannot
|
|
236
|
+
be reconstructed after a host restart. A smaller backward clock adjustment that
|
|
237
|
+
leaves `reservedAt` in the past can therefore prolong a reservation whose gate
|
|
238
|
+
still exists, such as a parent crash before spawn. The reservation remains
|
|
239
|
+
capacity-bearing until wall time reaches the age limit or an operator verifies
|
|
240
|
+
that no child can start and removes the record and gate. This limitation cannot
|
|
241
|
+
allow provider or command work past the gate: a spawned child independently
|
|
242
|
+
removes the gate and exits after its monotonic two-minute wait.
|
|
243
|
+
|
|
140
244
|
### `shift next [--wait <seconds>]`
|
|
141
245
|
|
|
142
246
|
```text
|
|
@@ -243,6 +347,87 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
|
243
347
|
| `settings` | print the resolved execution settings file |
|
|
244
348
|
| `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
|
|
245
349
|
|
|
350
|
+
### `work agent-run` — the only Step Agent dispatcher
|
|
351
|
+
|
|
352
|
+
`owenloop work agent-run` is the only supported way to dispatch an agent order.
|
|
353
|
+
The command resolves the verified local workflow definition, applies the final
|
|
354
|
+
`--harness` / environment / step harness selection, and checks every
|
|
355
|
+
`x.harness` restriction before cold start or resume. An unsupported restriction
|
|
356
|
+
starts no provider process, prints each exact refusal, releases the claim, and
|
|
357
|
+
exits `1`.
|
|
358
|
+
|
|
359
|
+
The Codex adapter refuses explicit `filesystem: read-only` and
|
|
360
|
+
`filesystem: workspace-write` before starting or resuming `codex app-server`.
|
|
361
|
+
The refusal is intentional: Codex configuration layers outside the thread
|
|
362
|
+
sandbox prevent the adapter from proving either neutral filesystem boundary.
|
|
363
|
+
Use the Claude Code adapter for the enforceable read-only/Owenloop-only policy,
|
|
364
|
+
or omit `filesystem` / declare `filesystem: unrestricted` only when the workflow
|
|
365
|
+
accepts the corresponding Codex behavior.
|
|
366
|
+
|
|
367
|
+
An absent `x.harness.tools` field preserves the adapter's default tool surface;
|
|
368
|
+
`tools: []` is an explicit empty allow-list. The two forms are not equivalent.
|
|
369
|
+
Invalid reserved fields and overlapping `tools` / `disallowedTools` are refused.
|
|
370
|
+
`owenloop work lint` runs the same common and adapter checks, but runtime
|
|
371
|
+
preflight remains authoritative because `--harness` or `OWENLOOP_HARNESS` can
|
|
372
|
+
select a different adapter after lint. See [Agent runner and harness policy](agent-runner.md)
|
|
373
|
+
for the capability matrix and the born-bound Owenloop control-plane exception.
|
|
374
|
+
|
|
375
|
+
**Harness-session durability.** `agent-run` records the provider session in the
|
|
376
|
+
machine-local `sessions.jsonl` log. The `active` row is a safety-critical gate:
|
|
377
|
+
the complete row and its trailing newline are written and fsynced before a
|
|
378
|
+
cold-start adapter may begin provider work or a resumed adapter may deliver new
|
|
379
|
+
feedback. Creating the log also fsyncs the containing directory where the
|
|
380
|
+
platform supports directory fsync. If the active append or fsync fails,
|
|
381
|
+
`agent-run` tears down the provider session, releases the order exactly once,
|
|
382
|
+
skips confirmation, writes no later lifecycle row, and exits with
|
|
383
|
+
`session-store-failed`. Later `turn-ended`, `submitted`, and `dead` rows keep
|
|
384
|
+
ordinary append durability; losing one causes conservative replay or retirement,
|
|
385
|
+
not unrecorded provider work. Compaction fsyncs the replacement before rename
|
|
386
|
+
and fsyncs the directory after rename so a successful compaction preserves a
|
|
387
|
+
previously durable active row.
|
|
388
|
+
|
|
389
|
+
## `trust` — local enrollment trust
|
|
390
|
+
|
|
391
|
+
The `trust` commands create the local enrollment root and signed enrollment
|
|
392
|
+
records. The commands are offline: they do not contact a hub or other remote
|
|
393
|
+
coordinator, and the remote side cannot create, sign, or endorse these records.
|
|
394
|
+
The org root is stored separately from `PrincipalKeyManager` at the injected
|
|
395
|
+
configuration root described in [Signing and key storage](crypto.md#enrollment-chains-attenuation-and-revocation).
|
|
396
|
+
|
|
397
|
+
```text
|
|
398
|
+
owenloop trust init [--force]
|
|
399
|
+
owenloop trust grant --key <pubkey-path> --principal <human|machine|agent>:<id> \
|
|
400
|
+
[--pools a,b|*] [--labels a,b|*] [--namespaces a,b|*] \
|
|
401
|
+
[--delegate no|<n>|unbounded] [--signing-key <path>] [--output <file>]
|
|
402
|
+
owenloop trust revoke --key <SHA256:…> --principal <kind>:<id> \
|
|
403
|
+
[--reason <text>] [--effective-from <epochMs>] \
|
|
404
|
+
[--signing-key <path>] [--output <file>]
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
- `trust init` generates an Ed25519 org-root key pair under the local config
|
|
408
|
+
directory. The containing directory is `0700`, the private key is `0600`,
|
|
409
|
+
and the public key is `0644`. Existing root files are refused unless
|
|
410
|
+
`--force` is supplied. The command prints paths and status, never private key
|
|
411
|
+
bytes.
|
|
412
|
+
- `trust grant` reads an Ed25519 public key from `--key`, assigns it to the
|
|
413
|
+
`--principal`, and signs an `EnrollmentGrantRecord`. Each scope axis defaults
|
|
414
|
+
to an empty array (deny by default); `--delegate` defaults to `no`. The
|
|
415
|
+
signing key defaults to the local org root unless `--signing-key` is given.
|
|
416
|
+
The signed DSSE envelope is written to `--output`, or to the local roster
|
|
417
|
+
directory using a SHA-256 hash of the enrolled key ID as its filename.
|
|
418
|
+
- `trust revoke` signs a `RevocationRecord` for the `SHA256:…` key in `--key`.
|
|
419
|
+
The signing key defaults to the local org root. Without `--effective-from`,
|
|
420
|
+
the cut starts at issuance. With an earlier `--effective-from`, the CLI
|
|
421
|
+
derives `backdated: true`; the flag is never accepted as an independent
|
|
422
|
+
boolean. The signed envelope is written to `--output`, or to the local
|
|
423
|
+
revocations directory using a SHA-256 hash of the revoked key ID.
|
|
424
|
+
|
|
425
|
+
These commands print one JSON result on success. They refuse malformed
|
|
426
|
+
principals, fingerprints, scope lists, delegation values, and timestamps before
|
|
427
|
+
performing the related filesystem or signing work. Trust records are only
|
|
428
|
+
local inputs to the chain validator; transporting a signed envelope is a
|
|
429
|
+
separate concern.
|
|
430
|
+
|
|
246
431
|
## `add` — installing shared workflow defs from GitHub
|
|
247
432
|
|
|
248
433
|
`owenloop add <owner>/<repo>[@ref]` fetches a public GitHub repo's
|
|
@@ -405,8 +590,8 @@ bounded — it only loads folders named by the fail-closed-validated
|
|
|
405
590
|
|
|
406
591
|
- **Only under the default defs dir.** An explicit `--defs`/`OWENLOOP_DEFS` is
|
|
407
592
|
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.
|
|
593
|
+
no installed-def or CAS-store fold-in — the rule is "was an override given",
|
|
594
|
+
so even `OWENLOOP_DEFS=$PWD/workflows` counts as an override and stays literal.
|
|
410
595
|
Pointing `--defs` straight at an install folder
|
|
411
596
|
(`--defs workflows/<owner>-<repo>-<hash>`) still works exactly as before.
|
|
412
597
|
- **Precedence.** Project-local (top-level) defs win over installed defs; among
|
|
@@ -471,14 +656,501 @@ refuses the whole install (nothing written) on any of these:
|
|
|
471
656
|
buffered into memory (the extraction limits above still re-check the size once
|
|
472
657
|
the bytes are in hand).
|
|
473
658
|
- **Request timeouts.** The sha-resolve fetch times out after 30s and the
|
|
474
|
-
tarball download after 5 min, each surfacing as a friendly error.
|
|
659
|
+
tarball download after 5 min, each surfacing as a friendly error. The
|
|
660
|
+
bundle route applies the same 256 MiB cap and 5 min timeout to its file
|
|
661
|
+
read and URL fetch (see the next section).
|
|
662
|
+
|
|
663
|
+
## `add` with bundles — the content-addressed workflow store
|
|
664
|
+
|
|
665
|
+
`owenloop add <owner>/<repo>[@ref]` (the previous section) installs
|
|
666
|
+
GitHub repos by name into `<defsDir>/<owner>-<repo>-<hash>/`. The **bundle**
|
|
667
|
+
route is a separate, content-addressed installation path for `.wnlp` workflow
|
|
668
|
+
bundles:
|
|
669
|
+
|
|
670
|
+
```text
|
|
671
|
+
owenloop add widget.wnlp # install into the PROJECT store
|
|
672
|
+
owenloop add ./packs/widget.wnlp --global # install into the GLOBAL store
|
|
673
|
+
owenloop add https://example.com/widget.wnlp
|
|
674
|
+
owenloop add --recover [--global] # offline crash recovery (per root)
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
The source is classified before anything else: `owner/repo[@ref]` keeps the
|
|
678
|
+
GitHub route byte-for-byte unchanged; a path ending in `.wnlp` is a bundle
|
|
679
|
+
file; an `http:`/`https:` URL is a bundle URL. Any other URL scheme
|
|
680
|
+
(`ftp:`, `file:`, …) is refused — never a silent fallback. `--global` applies
|
|
681
|
+
only to `.wnlp` bundle sources; a GitHub source with `--global` is refused
|
|
682
|
+
before any network request. The source string is origin data only (diagnostics
|
|
683
|
+
and messages); it is never joined into a filesystem path and never part of a
|
|
684
|
+
bundle's identity. Identity comes from the bundle's own
|
|
685
|
+
`namespace/name@version` coordinate and its canonical content digest.
|
|
686
|
+
|
|
687
|
+
**The `.wnlp` route requires two adapters and fails closed without them.**
|
|
688
|
+
Bundle ingestion (unpacking, manifest integrity, canonical digest,
|
|
689
|
+
coordinate) and pre-commit verification are separate modules with no
|
|
690
|
+
permissive fallback: with either adapter missing, `add` refuses with a named
|
|
691
|
+
error before any staging, journal, or index write. The default CLI binds both
|
|
692
|
+
production adapters. The pre-commit verifier consumes the publication sidecars
|
|
693
|
+
written by `publish` and applies the local `defPolicy` before the object or index
|
|
694
|
+
commit. Hosts that provide both adapters can install real `.wnlp` output from
|
|
695
|
+
`packBundle`; use the `publish` command to create the `.wnlp` bundle plus a
|
|
696
|
+
signed or explicitly unsigned sidecar.
|
|
697
|
+
|
|
698
|
+
### Definition publication policy
|
|
699
|
+
|
|
700
|
+
`defPolicy` is the local execution and installation policy for workflow
|
|
701
|
+
publication signatures. The settings file is
|
|
702
|
+
`$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is non-blank,
|
|
703
|
+
otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
|
|
704
|
+
settings file, write a JSON object such as:
|
|
705
|
+
|
|
706
|
+
```json
|
|
707
|
+
{
|
|
708
|
+
"defPolicy": "enforce"
|
|
709
|
+
}
|
|
710
|
+
```
|
|
711
|
+
|
|
712
|
+
For a one-off CLI invocation, set `OWENLOOP_DEF_POLICY` in the environment, for
|
|
713
|
+
example `OWENLOOP_DEF_POLICY=enforce owenloop add widget.wnlp`. The local
|
|
714
|
+
precedence is explicit host-provided policy, then `OWENLOOP_DEF_POLICY`, then
|
|
715
|
+
the settings file, then the built-in default `warn`. An invalid environment or
|
|
716
|
+
settings-file value fails loudly; it never degrades to `off`.
|
|
717
|
+
|
|
718
|
+
When a host supplies an already-verified organization policy floor through the
|
|
719
|
+
`policyFloor` option seam, the floor is applied **after** that local precedence.
|
|
720
|
+
`unsignedDefs: warn` raises the minimum to `warn`; `unsignedDefs: refuse` raises
|
|
721
|
+
the minimum to `enforce`; the effective policy is the stricter of local policy
|
|
722
|
+
and the floor. **Therefore, local `off` no longer means “no enforcement” when a
|
|
723
|
+
verified org floor is present.** A local operator cannot use `off` to opt out of
|
|
724
|
+
a verified floor. A missing, malformed, unsigned, wrongly signed, or
|
|
725
|
+
under-scoped floor leaves the local policy unchanged.
|
|
726
|
+
|
|
727
|
+
The current CLI and production configuration do not load or verify a floor.
|
|
728
|
+
`policyFloor` is an injection seam only, so this feature is inert until a host
|
|
729
|
+
wires floor loading and verification into that seam.
|
|
730
|
+
|
|
731
|
+
The policy applies at install time and again at execution time. The following
|
|
732
|
+
table describes the local policy result before any verified floor is applied.
|
|
733
|
+
The table uses these verdicts:
|
|
734
|
+
|
|
735
|
+
- `verified` — the publication sidecar verifies against the bundle digest and a
|
|
736
|
+
signer in the local trust root.
|
|
737
|
+
- `unsigned` — the bundle has no publication signature (including an explicit
|
|
738
|
+
`.wnlp.unsigned` sidecar).
|
|
739
|
+
- `unverifiable` — verification could not be completed, such as when the trust
|
|
740
|
+
root is missing or malformed.
|
|
741
|
+
- `invalid` — a present publication signature fails verification, including a
|
|
742
|
+
digest or signer mismatch.
|
|
743
|
+
|
|
744
|
+
| publication verdict | `enforce` | `warn` | `off` |
|
|
745
|
+
|---|---|---|---|
|
|
746
|
+
| `verified` | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. | Install succeeds; agent and command execution proceed. |
|
|
747
|
+
| `unsigned` or `unverifiable` | Install refuses; agent and command execution refuse. | Install warns to stderr and succeeds; agent execution warns and proceeds; command execution refuses. | Install succeeds silently; agent execution proceeds silently; command execution refuses. |
|
|
748
|
+
| `invalid` | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. | Install refuses; agent and command execution refuse. |
|
|
749
|
+
|
|
750
|
+
**Command-worker hard rule.** A `worker: command` order requires full
|
|
751
|
+
enforcement in every policy value, including `off`: the definition must be
|
|
752
|
+
verified, the enrollment chain must be verified, and the signer scope must be
|
|
753
|
+
checked. `off` does not disable command-worker enforcement. `warn` and `off`
|
|
754
|
+
never allow an unsigned, unverifiable, or invalid definition to reach the
|
|
755
|
+
shell. The command check runs before the policy value is read, and a refusal
|
|
756
|
+
uses the normal `InstructionRefusal` path so the lease stops before command
|
|
757
|
+
execution. A policy floor cannot relax this gate; the gate also fails closed
|
|
758
|
+
regardless of any floor. If an execution host has no publication verifier
|
|
759
|
+
configured, the definition is `unverifiable`; command workers therefore refuse
|
|
760
|
+
rather than treating installed bytes as published trust.
|
|
761
|
+
|
|
762
|
+
### Consume-side artifact policy
|
|
763
|
+
|
|
764
|
+
`artifactPolicy` controls how agent and MCP drivers handle absent evidence and
|
|
765
|
+
missing local prerequisites for signed dynamic artifact values. Supplied but
|
|
766
|
+
invalid evidence always refuses; the policy is a scalar with the same values as
|
|
767
|
+
`defPolicy`: `enforce`, `warn`, or `off`. The precedence is explicit host
|
|
768
|
+
option, then `OWENLOOP_ARTIFACT_POLICY`, then the `artifactPolicy` key in the
|
|
769
|
+
execution settings file, then the built-in default `warn`.
|
|
770
|
+
|
|
771
|
+
For example, the settings file can contain:
|
|
772
|
+
|
|
773
|
+
```json
|
|
774
|
+
{
|
|
775
|
+
"artifactPolicy": "enforce"
|
|
776
|
+
}
|
|
777
|
+
```
|
|
778
|
+
|
|
779
|
+
A one-off invocation can set
|
|
780
|
+
`OWENLOOP_ARTIFACT_POLICY=enforce owenloop work agent-run <order-id>`.
|
|
781
|
+
Invalid values fail loudly; an invalid value never becomes `off`.
|
|
782
|
+
|
|
783
|
+
The consuming driver verifies each delivered value against its serialized DSSE
|
|
784
|
+
submission proof, the signed value digest and version, the locally anchored
|
|
785
|
+
producer enrollment chain, revocations, and any supplied consuming demand's
|
|
786
|
+
scope. A missing proof is not the same as invalid evidence. Dynamic values and
|
|
787
|
+
rejection reasons remain on the wire; the driver verifies those values and
|
|
788
|
+
refuses the whole order on failure rather than dropping only one path.
|
|
789
|
+
|
|
790
|
+
A valid historical proof is not enough to establish the version claimed for the
|
|
791
|
+
current delivery. Ordinary consumed artifacts bind the signed version to the
|
|
792
|
+
claim-time version in `consumedFingerprint`; owed rejection reasons bind to the
|
|
793
|
+
owed claim-time version. If that authoritative expected version is absent, the
|
|
794
|
+
verdict is `unverifiable`, never `verified`, even when the signature, value
|
|
795
|
+
digest, and enrollment chain all verify. The policy table therefore applies
|
|
796
|
+
without a hidden exception: `enforce` refuses that artifact, `warn` warns and
|
|
797
|
+
admits it, and `off` admits it without calling the proof verified. The
|
|
798
|
+
command-worker hard rule below still refuses it under every policy.
|
|
799
|
+
|
|
800
|
+
The current production `exec`, `agent-run`, and `hold` roles do not supply a
|
|
801
|
+
pool, label, or namespace demand. `OrderPacket` has no such demand field to
|
|
802
|
+
derive, so production consume gates enforce the enrollment chain, attenuation,
|
|
803
|
+
and revocation checks but do not apply a demand-dependent `scopePermits`
|
|
804
|
+
restriction. A caller that supplies a demand through the verifier seam gets the
|
|
805
|
+
full scope check. This limitation is a named follow-up.
|
|
806
|
+
|
|
807
|
+
| consumed-evidence verdict | `artifactPolicy=enforce` | `artifactPolicy=warn` | `artifactPolicy=off` |
|
|
808
|
+
|---|---|---|---|
|
|
809
|
+
| `verified` | admit | admit | admit |
|
|
810
|
+
| `absent` | refuse | warn and admit | admit |
|
|
811
|
+
| `unverifiable` | refuse | warn and admit | admit |
|
|
812
|
+
| `invalid` | refuse | refuse | refuse |
|
|
813
|
+
|
|
814
|
+
A refusal is an actionable integrity event. The refusal names the failed link
|
|
815
|
+
and artifact, using names such as `no-proof`, `signature`, `value-digest`,
|
|
816
|
+
`version`, `chain`, `scope`, or `prerequisite`, and includes the workflow, run,
|
|
817
|
+
and step. The driver refuses the whole order; operators must not suppress the
|
|
818
|
+
message or continue with a manually stripped packet.
|
|
819
|
+
|
|
820
|
+
The policy floor's `unsignedArtifacts: warn` value raises the local minimum to
|
|
821
|
+
`artifactPolicy=warn`; `unsignedArtifacts: refuse` raises it to `enforce`. A
|
|
822
|
+
verified floor is merged after local precedence, so local `off` cannot weaken
|
|
823
|
+
the floor.
|
|
824
|
+
|
|
825
|
+
**Command-worker hard rule.** A `worker: command` order refuses `absent`,
|
|
826
|
+
`unverifiable`, and `invalid` consumed evidence regardless of `artifactPolicy`,
|
|
827
|
+
including `off`. The consume-side gate runs before origin or artifact policy
|
|
828
|
+
lookup and before a shell command is built or passed to `/bin/sh -c`. A command
|
|
829
|
+
worker must have a configured consume-side verifier; an unverified dynamic value
|
|
830
|
+
must never reach the shell. Agent prompt rendering and MCP `get_order` likewise
|
|
831
|
+
fail closed when dynamic data exists but no verifier is configured. The driver
|
|
832
|
+
samples the consumer's injected clock once per complete gate invocation; a
|
|
833
|
+
revocation effective at `effectiveFrom <= at` makes a previously consumable
|
|
834
|
+
artifact unconsumable on a later invocation.
|
|
835
|
+
|
|
836
|
+
### Definition origin policy
|
|
837
|
+
|
|
838
|
+
`originRules` is a separate namespace-scoped provenance policy. A signed file
|
|
839
|
+
publication may include `<bundle>.origin.dsse`; installation verifies that
|
|
840
|
+
sidecar against the local `allowed_signers` root and retains the exact bytes at
|
|
841
|
+
`<store-root>/.owenloop/origins/<digest>.dsse`. Execution re-verifies the
|
|
842
|
+
retained evidence against the current trust root. Only a `verified` origin
|
|
843
|
+
verdict is retained. A bundle carrying only `<bundle>.origin.dsse` — with
|
|
844
|
+
neither a publication `.dsse` nor an unsigned marker — is refused at install for
|
|
845
|
+
every origin-policy value, including `off`. `publish` never emits that shape;
|
|
846
|
+
`--unsigned` removes both sidecars. A hub or other remote coordinator may relay
|
|
847
|
+
the sidecar, but never authors or supplies the origin rule.
|
|
848
|
+
|
|
849
|
+
The origin mode uses the same policy values as `defPolicy` — `enforce`, `warn`,
|
|
850
|
+
and `off` — and follows the same scalar precedence: explicit host option,
|
|
851
|
+
`OWENLOOP_ORIGIN_POLICY`, settings-file `originPolicy`, then `warn`. These are
|
|
852
|
+
not trust modes: `Seamless`, `Strict`, and `Paranoid` are a separate axis;
|
|
853
|
+
`Seamless` maps to `warn`, `Strict` maps to `enforce`, and `off` is a local
|
|
854
|
+
operator escape hatch with no trust-mode equivalent. The rule map has no
|
|
855
|
+
environment-variable spelling: explicit host `originRules`, then settings-file
|
|
856
|
+
`originRules`, then an empty map. A namespace with no matching rule has no origin
|
|
857
|
+
requirement. A malformed rule map is a named settings error, not an empty-policy
|
|
858
|
+
fallback.
|
|
859
|
+
|
|
860
|
+
Rules accept exact namespaces (`prod`), namespace prefixes (`prod*`), and
|
|
861
|
+
trailing `/*` sugar (`prod/*`, equivalent to `prod`). `*` and `*/*` are
|
|
862
|
+
catch-all rules. Exact matches beat prefixes; the longest prefix wins; keys
|
|
863
|
+
that normalize to equal specificity, such as `prod` and `prod/*`, are rejected.
|
|
864
|
+
Rule values are minimum provenance strengths, ordered `git` > `console` >
|
|
865
|
+
`agent`; therefore a `console` rule accepts verified `git` and `console`
|
|
866
|
+
origins, and an `agent` rule accepts all three. `any` imposes no requirement.
|
|
867
|
+
|
|
868
|
+
Origin verdicts remain distinct:
|
|
869
|
+
|
|
870
|
+
- `verified` has a strength and is checked against the selected minimum.
|
|
871
|
+
- `absent` means no origin bytes are available. For a signed file publication,
|
|
872
|
+
this means no sidecar was recorded. Unsigned publications and non-file install
|
|
873
|
+
sources also produce `absent`, but those definitions structurally cannot carry
|
|
874
|
+
an origin; those cases must not be described as “no origin was recorded.”
|
|
875
|
+
- `unverifiable` means a prerequisite such as the trust root is unavailable.
|
|
876
|
+
- `invalid` means present origin evidence failed verification and is refused at
|
|
877
|
+
every origin mode, including `off`.
|
|
878
|
+
|
|
879
|
+
For a matched rule, the local origin mode behaves as follows:
|
|
880
|
+
|
|
881
|
+
| origin verdict | `originPolicy=enforce` | `originPolicy=warn` | `originPolicy=off` |
|
|
882
|
+
|---|---|---|---|
|
|
883
|
+
| `verified` meeting the minimum | Install and execution succeed. | Install and execution succeed. | Install and execution succeed. |
|
|
884
|
+
| `verified` weaker than the minimum | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
|
|
885
|
+
| `absent` or `unverifiable` | Install refuses; execution refuses. | Install warns and succeeds; execution warns and proceeds. | Install and execution proceed silently. |
|
|
886
|
+
| `invalid` | Install refuses; execution refuses. | Install refuses; execution refuses. | Install refuses; execution refuses. |
|
|
887
|
+
|
|
888
|
+
The table applies only when a rule matches. During execution, the driver
|
|
889
|
+
recovers the namespace by reverse-scanning project and global store indexes for
|
|
890
|
+
the bundle digest. Equivalent requirements deduplicate. Different requirements
|
|
891
|
+
produce a named ambiguity refusal. If no coordinate is indexed, `enforce`
|
|
892
|
+
refuses, `warn` warns, and `off` proceeds. With an empty `originRules` map, the
|
|
893
|
+
default resolver still invokes the origin verifier once per order, but skips the
|
|
894
|
+
expensive index reverse-scan; invalid retained origin evidence still refuses.
|
|
895
|
+
|
|
896
|
+
A verified policy floor maps `originRules: advisory` to minimum
|
|
897
|
+
`originPolicy=warn` and `originRules: enforced` to minimum
|
|
898
|
+
`originPolicy=enforce`. The origin floor is parallel to the publication floor;
|
|
899
|
+
it does not alter `defPolicy`.
|
|
900
|
+
|
|
901
|
+
**Origin policy never relaxes the command-worker hard rule.** A
|
|
902
|
+
`worker: command` order must pass the publication verification gate first, even
|
|
903
|
+
when `defPolicy=off`, and only then runs the origin check. Unsigned,
|
|
904
|
+
unverifiable, or invalid publication evidence never reaches the shell. An
|
|
905
|
+
origin mode of `off` and every policy-floor preset leave that gate unchanged.
|
|
906
|
+
|
|
907
|
+
The local SSHSIG trust root is
|
|
908
|
+
`$XDG_CONFIG_HOME/owenloop/allowed_signers`, or
|
|
909
|
+
`$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
|
|
910
|
+
missing or malformed trust root is `unverifiable`, not `unsigned`.
|
|
911
|
+
|
|
912
|
+
### The two store roots
|
|
913
|
+
|
|
914
|
+
A store root holds exactly this layout:
|
|
915
|
+
|
|
916
|
+
```text
|
|
917
|
+
<root>/
|
|
918
|
+
index.json # coordinate → {digest, pinned, workflows?} index
|
|
919
|
+
objects/
|
|
920
|
+
sha256/
|
|
921
|
+
<64-hex-content-digest>/ # one immutable object per digest
|
|
922
|
+
… # the bundle's files
|
|
923
|
+
.owenloop/ # per-root lock + crash journal
|
|
924
|
+
add.lock
|
|
925
|
+
add.journal
|
|
926
|
+
.owenloop-staging/ # transient staging (cleared on exit)
|
|
927
|
+
```
|
|
475
928
|
|
|
476
|
-
|
|
929
|
+
- **Project store root** = the resolved defs directory itself (`--defs`,
|
|
930
|
+
`OWENLOOP_DEFS`, or `./workflows`). The project's pins are reviewable in
|
|
931
|
+
git there, and the nested `objects/sha256/<digest>/` layout stays below
|
|
932
|
+
the def loader's scan depth.
|
|
933
|
+
- **Global store root** = `<home>/.owenloop/workflows`. `--global` selects it;
|
|
934
|
+
it cannot be combined with `--defs` (the global store has a fixed
|
|
935
|
+
home-directory location, so an override would only create ambiguity —
|
|
936
|
+
refused with a clear message). The global root is never used by the
|
|
937
|
+
GitHub route.
|
|
938
|
+
|
|
939
|
+
**Injected home requirement.** `<home>` is the first non-blank value from the
|
|
940
|
+
caller-injected `HOME` and `USERPROFILE` environment variables (`HOME` wins).
|
|
941
|
+
The `.wnlp` bundle route uses the same injected home for its default external
|
|
942
|
+
recovery-marker directory, `<home>/.owenloop/recovery-markers`, even when the
|
|
943
|
+
bundle targets the project store. If neither variable is supplied, bundle
|
|
944
|
+
installation refuses before any object or index commit; it never falls back to
|
|
945
|
+
the process user's ambient home. `add --recover --global` has the same
|
|
946
|
+
requirement. Project recovery of a v2 fresh-install journal also refuses when
|
|
947
|
+
its recovery marker requires a home and neither variable is supplied.
|
|
948
|
+
|
|
949
|
+
Every object path derives ONLY from its validated digest (lowercase 64-hex).
|
|
950
|
+
Coordinates, source strings, and version text never join into a path.
|
|
951
|
+
|
|
952
|
+
### What an install does, in order
|
|
953
|
+
|
|
954
|
+
1. Read the bundle bytes (file or URL) *before* taking the lock — a slow
|
|
955
|
+
download never holds the project lock. A local `.wnlp` must be a bounded
|
|
956
|
+
regular file: missing, symlinked, non-regular, or over the 256 MiB cap
|
|
957
|
+
(checked before *and* after the read) is refused naming the path as
|
|
958
|
+
given. A URL fetch uses the same 5 min timeout, refuses redirects
|
|
959
|
+
(`redirect: 'error'`) instead of following them silently, and streams
|
|
960
|
+
through the same bounded reader.
|
|
961
|
+
2. Acquire the canonical root lock at `<root>/.owenloop/add.lock`. A GitHub
|
|
962
|
+
install also retains its legacy cwd-derived lock for compatibility and, when
|
|
963
|
+
the resolved `--defs` root differs from that cwd, acquires both locks in a
|
|
964
|
+
fixed order. The canonical lock makes bundle installs from different cwd
|
|
965
|
+
values serialize when they target one shared `--defs` root; the additional
|
|
966
|
+
GitHub lock keeps the legacy route compatible.
|
|
967
|
+
3. Recover a prior interrupted install (before clearing staging — the
|
|
968
|
+
backups a rollback needs live under the staging root).
|
|
969
|
+
4. Reread and validate the index **inside** the lock (a corrupt index is a
|
|
970
|
+
hard error, never a silent reset).
|
|
971
|
+
5. Ingest via the bundle adapter: unpack into staging, check manifest
|
|
972
|
+
integrity and runtime compatibility, compute the canonical digest, and
|
|
973
|
+
extract the full coordinate. The runtime check uses Owenloop's production
|
|
974
|
+
package version and advertised feature set. A tampered, malformed, or
|
|
975
|
+
runtime-incompatible bundle stops here — staging debris only, nothing
|
|
976
|
+
committed.
|
|
977
|
+
6. Validate the staged tree with the engine's strict pass — the exact bytes
|
|
978
|
+
that will be committed (parse/lint/validate/bounded `check` + the strict
|
|
979
|
+
cross-def backstop). For a real `.wnlp`, validation parses `bundle.yaml`
|
|
980
|
+
through the same runtime-admission boundary and loads every workflow path
|
|
981
|
+
listed in its `workflows` map; the package manifest itself is not treated as
|
|
982
|
+
a workflow definition. Any problem refuses the whole install and prints
|
|
983
|
+
every reason.
|
|
984
|
+
7. Run the pre-commit verifier (after content validation, before any swap or
|
|
985
|
+
index write). A rejection commits nothing.
|
|
986
|
+
8. Write the `applying` crash journal (v2 — its commit-point evidence is the
|
|
987
|
+
hash of the post-install index bytes).
|
|
988
|
+
9. Atomically swap the staged object into `objects/sha256/<digest>`
|
|
989
|
+
(retaining any displaced content on the commit handle), then harden it
|
|
990
|
+
in place: canonical `0644` files become read-only `0444`, canonical `0755`
|
|
991
|
+
files become read/execute-only `0555`, and directories become non-writable
|
|
992
|
+
`0555`. Hardening preserves the executable distinction needed for canonical
|
|
993
|
+
object reconstruction. Hardening is defense in depth, not the integrity proof
|
|
994
|
+
— verification reconstructs the complete canonical tar, including
|
|
995
|
+
`bundle.yaml`, and matches its SHA-256 digest to the object path. A hardening
|
|
996
|
+
failure rolls the swap back; a partially hardened object is never committed.
|
|
997
|
+
If the digest's object already exists, the install verifies the existing
|
|
998
|
+
object through the ingest adapter and commits an index-only change instead
|
|
999
|
+
(dedupe) — a corrupt or runtime-incompatible existing object is a hard
|
|
1000
|
+
integrity error, never replaced and never fallen through.
|
|
1001
|
+
10. Atomically write `index.json` — the **durable commit point**. Past here
|
|
1002
|
+
a crash rolls forward; before it, everything rolls back. An index-write
|
|
1003
|
+
failure rolls the directory state back and leaves the previous object
|
|
1004
|
+
and index exactly as they were.
|
|
1005
|
+
11. Advance the journal to `finalizing`, discard the retained backup and
|
|
1006
|
+
staging, remove the journal, release the lock.
|
|
1007
|
+
|
|
1008
|
+
On success `add` prints the structured result:
|
|
477
1009
|
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
1010
|
+
```jsonc
|
|
1011
|
+
{
|
|
1012
|
+
"ok": true,
|
|
1013
|
+
"source": "widget.wnlp", // or the URL
|
|
1014
|
+
"level": "project", // or "global"
|
|
1015
|
+
"coordinate": "acme/widget@1.0.0",
|
|
1016
|
+
"digest": "<64-hex>",
|
|
1017
|
+
"workflows": ["delivery", "init"], // every workflow name in the bundle, sorted
|
|
1018
|
+
"objectPath": "<root>/objects/sha256/<64-hex>",
|
|
1019
|
+
"installed": true // false when deduplicated
|
|
1020
|
+
}
|
|
1021
|
+
```
|
|
1022
|
+
|
|
1023
|
+
**Conflict and re-install.** An existing coordinate at a DIFFERENT digest is
|
|
1024
|
+
a conflict error — no implicit retarget; the original digest is retained and
|
|
1025
|
+
nothing is written. An existing coordinate at the SAME digest deduplicates
|
|
1026
|
+
(`installed: false`), verifying the existing object before trusting it.
|
|
1027
|
+
|
|
1028
|
+
**Crash recovery** is the same two-phase discipline as the GitHub route,
|
|
1029
|
+
generalized: the v2 journal's commit-point test compares the hash of the
|
|
1030
|
+
current `index.json` bytes against the journal's recorded metadata hash
|
|
1031
|
+
(route-neutral — no GitHub ledger involved). A fresh v2 install also writes a
|
|
1032
|
+
single-use external recovery marker under the user's recovery-marker directory
|
|
1033
|
+
(default `<home>/.owenloop/recovery-markers`, derived from the injected home
|
|
1034
|
+
described above) before the applying journal. If a crash leaves the destination
|
|
1035
|
+
present with no staging or backup, recovery
|
|
1036
|
+
discards that destination only when the marker exactly matches the store root,
|
|
1037
|
+
destination segments, staging id, and `hadDest: false`; a missing or mismatched
|
|
1038
|
+
marker refuses and preserves the destination and journal. `add --recover --global`
|
|
1039
|
+
runs the store's recovery standalone against the global root with no network
|
|
1040
|
+
and prints `{"ok":true,"recovered":false|true,"outcome":…}` exactly
|
|
1041
|
+
like the project variant. A v1 (GitHub-schema) journal found at the global root
|
|
1042
|
+
is refused fail-closed — there is no ledger there to vouch for it — and a
|
|
1043
|
+
journal recorded against a *different* store root is refused rather than
|
|
1044
|
+
trusting its absolute path. Refusals leave the journal in place as evidence.
|
|
1045
|
+
|
|
1046
|
+
### Resolving what is installed — two separate APIs
|
|
1047
|
+
|
|
1048
|
+
Resolution is deliberately split so execution code cannot accidentally call
|
|
1049
|
+
human-name resolution. Both are library APIs (exported from the package
|
|
1050
|
+
root); every successful resolution verifies the object through the ingest
|
|
1051
|
+
adapter before returning a path — permissions and object shape on disk are
|
|
1052
|
+
defense in depth, not an integrity proof.
|
|
1053
|
+
|
|
1054
|
+
- **Digest resolution (execution).** `resolveWorkflowDigest({digest,
|
|
1055
|
+
projectRoot?, globalRoot, verifier})` — digest only; no index and no
|
|
1056
|
+
workflow name participate. The project object path is tested first when a
|
|
1057
|
+
project root exists; an ABSENT project object may fall through to global,
|
|
1058
|
+
but a PRESENT project object that fails its type probe or verification is
|
|
1059
|
+
a hard integrity error — project tampering is never hidden by falling back
|
|
1060
|
+
to a valid global copy. When both levels hold the same digest, ONE result
|
|
1061
|
+
comes back (level `project`, with presence metadata), not two candidates.
|
|
1062
|
+
Absent at both levels ⇒ `object-missing` integrity error.
|
|
1063
|
+
- **Coordinate resolution (human/CLI).** `resolveWorkflowCoordinate({coordinate,
|
|
1064
|
+
projectRoot?, globalRoot, verifier})` reads BOTH indexes, fail-closed (a
|
|
1065
|
+
corrupt index is a hard error, never silently empty). No entry at either
|
|
1066
|
+
level ⇒ a structured **not-found** error. A project entry wins whenever it
|
|
1067
|
+
exists, even when the global index maps the same coordinate to a different
|
|
1068
|
+
digest; global is the fallback only when project has no match. An index entry
|
|
1069
|
+
whose selected object is missing or corrupt is an integrity error, never a
|
|
1070
|
+
returned path.
|
|
1071
|
+
|
|
1072
|
+
**Calls resolution for installed bundle workflows.** In the default CLI context
|
|
1073
|
+
(no explicit `--defs`/`OWENLOOP_DEFS`), `defs`/`create`/`tick` load CAS workflows
|
|
1074
|
+
from the project and global bundle-store indexes in addition to filesystem defs
|
|
1075
|
+
and the GitHub `add` ledger. A CAS workflow is addressable by the qualified
|
|
1076
|
+
`<package>/<workflow>` name, so a project-local or `add`-installed workflow can
|
|
1077
|
+
call it explicitly. A bare call from a CAS-loaded workflow resolves a sibling
|
|
1078
|
+
from the same bundle digest first; if no sibling has that name, ordinary flat
|
|
1079
|
+
lookup remains available. Bare CAS names are not registered globally, so a
|
|
1080
|
+
workflow in bundle A cannot accidentally call a same-named workflow from bundle
|
|
1081
|
+
B.
|
|
1082
|
+
|
|
1083
|
+
The precedence is explicit: project-local definitions win first, then
|
|
1084
|
+
GitHub-`add` installed definitions, then CAS definitions under qualified keys.
|
|
1085
|
+
Within the CAS layer, exactly one installed bundle holds the unqualified
|
|
1086
|
+
`<package>/<workflow>` name, chosen by two rules in order and never by install
|
|
1087
|
+
order:
|
|
1088
|
+
|
|
1089
|
+
1. **Level.** If any candidate is named by the *project* index, only project
|
|
1090
|
+
candidates compete. A project pin of `pkg@0.1.0` therefore beats a global
|
|
1091
|
+
install of `pkg@0.9.9`. This holds even when the project's own object bytes
|
|
1092
|
+
are missing and were served by exact-digest fallback from the global store —
|
|
1093
|
+
the index that names the object decides, not where the bytes were read.
|
|
1094
|
+
2. **Version.** Among the survivors, the highest canonical SemVer precedence
|
|
1095
|
+
wins (SemVer §11, so `0.1.10` beats `0.1.2` and `1.0.0` beats `1.0.0-rc.1`).
|
|
1096
|
+
|
|
1097
|
+
A canonical SemVer version never loses to a non-SemVer one. If two or more
|
|
1098
|
+
candidates compete and *none* carries a canonical SemVer version, the selection
|
|
1099
|
+
**fails closed**: the unqualified name is left unregistered and a warning names
|
|
1100
|
+
the versions involved, because there is no defined precedence to pick by. Call an
|
|
1101
|
+
exact `<namespace>/<name>@<version>` coordinate in that case. A single
|
|
1102
|
+
non-SemVer version still holds its name — there is nothing to order.
|
|
1103
|
+
|
|
1104
|
+
The refusal warning names only the versions that actually competed. A version
|
|
1105
|
+
dropped by rule 1 is reported separately as never having competed, since it lost
|
|
1106
|
+
on level and was never judged on its version at all. For the same reason,
|
|
1107
|
+
precedence warnings say `project-indexed` / `global-indexed`: precedence follows
|
|
1108
|
+
the index that named the object, whereas a registration's reported level is the
|
|
1109
|
+
store its verified bytes came from, and the two differ under exact-digest
|
|
1110
|
+
fallback.
|
|
1111
|
+
|
|
1112
|
+
Every version that did not win remains reachable under its digest-scoped key, so
|
|
1113
|
+
an already-pinned execution cannot be retargeted, and every exact
|
|
1114
|
+
`<namespace>/<name>@<version>` coordinate always resolves to its own object
|
|
1115
|
+
regardless of which version currently holds the unqualified name.
|
|
1116
|
+
A corrupt CAS index, object, or workflow is skipped with a warning during
|
|
1117
|
+
read-side discovery, so it does not make `status` fail. A running workflow keeps
|
|
1118
|
+
the definition snapshot from its creation (§28), including the CAS bundle
|
|
1119
|
+
provenance used for sibling lookup; installing a newer bundle therefore does not
|
|
1120
|
+
retarget an existing parent instance. The bundle spawn-time pin check compares
|
|
1121
|
+
canonical bundle digests and records a rejected `calls:` debt instead of running
|
|
1122
|
+
a mismatched child.
|
|
1123
|
+
|
|
1124
|
+
Store roots and object directories are probed with `lstat`, never `stat`:
|
|
1125
|
+
a symlink or non-directory squatting at a root, an index path, or an object
|
|
1126
|
+
path is refused outright, and reads never follow a link outside the
|
|
1127
|
+
intended tree.
|
|
1128
|
+
|
|
1129
|
+
**GitHub-route compatibility.** The bundle route changes nothing about
|
|
1130
|
+
`add <owner>/<repo>[@ref]`: the same inputs reach the same parser, the
|
|
1131
|
+
`<owner>-<repo>-<hash>` namespace is untouched, `.owenloop/installed.json`
|
|
1132
|
+
keeps its schema and validation, and an explicit `--defs`/`OWENLOOP_DEFS`
|
|
1133
|
+
still installs through a symlinked defs dir (operator intent). The legacy
|
|
1134
|
+
GitHub repository route installs workflow YAML rather than a format-v2
|
|
1135
|
+
`bundle.yaml`; therefore the GitHub route does not carry or enforce the `.wnlp`
|
|
1136
|
+
runtime compatibility declaration and does not provide the `.wnlp` runtime
|
|
1137
|
+
admission guarantee. Use a `.wnlp` bundle when the publisher must declare a
|
|
1138
|
+
minimum Owenloop version or required runtime features.
|
|
1139
|
+
|
|
1140
|
+
The routes share the canonical resolved-store lock, while the GitHub route
|
|
1141
|
+
retains its legacy cwd-derived lock and journal for compatibility. Recovery
|
|
1142
|
+
checks both journal locations and dispatches by journal version; a v2 store
|
|
1143
|
+
journal uses `index.json` metadata and a v1 GitHub journal uses
|
|
1144
|
+
`installed.json` ledger corroboration.
|
|
1145
|
+
|
|
1146
|
+
## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
|
|
1147
|
+
|
|
1148
|
+
These commands authenticate, publish, and start workflows on a hosted **hub** (default
|
|
1149
|
+
`https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
|
|
1150
|
+
`--hub <url>` → `OWENLOOP_HUB` → the built-in `DEFAULT_HUB`. `connect`, `push`,
|
|
1151
|
+
and `publish` use the safer publishing ladder below and never consult
|
|
1152
|
+
`OWENLOOP_HUB` or guess `DEFAULT_HUB`. They are the only network-bound commands
|
|
1153
|
+
besides `add`, and they talk only to endpoints the hub exposes today — no new
|
|
482
1154
|
service-side surface. The hub URL is normalized to its origin
|
|
483
1155
|
(`scheme://host[:port]`); path/query are dropped. `https` is required for
|
|
484
1156
|
every hub origin except the loopback hosts (`127.0.0.1`, `::1`, `localhost`),
|
|
@@ -492,6 +1164,74 @@ bounce credentials or workflow YAML to another origin (same-origin validation
|
|
|
492
1164
|
covers only the initial URL; a redirect would otherwise re-send the request body
|
|
493
1165
|
cross-origin).
|
|
494
1166
|
|
|
1167
|
+
### The small hosted-workflow path
|
|
1168
|
+
|
|
1169
|
+
Setup is durable. Authenticate and bind the project once, publish or update a
|
|
1170
|
+
definition when its content changes, prepare that published version for the
|
|
1171
|
+
execution account, and keep one crew-scoped Shift running:
|
|
1172
|
+
|
|
1173
|
+
```bash
|
|
1174
|
+
owenloop login --hub https://hub.example
|
|
1175
|
+
owenloop connect --hub https://hub.example
|
|
1176
|
+
owenloop push newhire-onboarding
|
|
1177
|
+
OWENLOOP_ACCOUNT=default owenloop work prepare newhire-onboarding --origin https://hub.example
|
|
1178
|
+
OWENLOOP_HARNESS=codex owenloop shift start openai --origin https://hub.example --as default
|
|
1179
|
+
```
|
|
1180
|
+
|
|
1181
|
+
Starting another run does not repeat installation, publication, preparation,
|
|
1182
|
+
or Shift setup. From the connected project it is one public control-plane
|
|
1183
|
+
command; repeat `--provide name=json` for seeded human inputs:
|
|
1184
|
+
|
|
1185
|
+
```bash
|
|
1186
|
+
owenloop start newhire-onboarding \
|
|
1187
|
+
--crew openai \
|
|
1188
|
+
--provide 'signed_docs={"acknowledged":true}' \
|
|
1189
|
+
--provide 'hardware_choice={"laptop":"MacBook Pro"}'
|
|
1190
|
+
```
|
|
1191
|
+
|
|
1192
|
+
`start` always uses the human credential. The standing Shift uses the
|
|
1193
|
+
`agent:default` credential selected by `--as default`. With no project binding,
|
|
1194
|
+
`start --hub <url>` is accepted explicitly; with neither a binding nor `--hub`,
|
|
1195
|
+
it refuses instead of falling through to `OWENLOOP_HUB` or the production
|
|
1196
|
+
default. If both a binding and `--hub` exist they must agree.
|
|
1197
|
+
|
|
1198
|
+
### `start` — start a published workflow
|
|
1199
|
+
|
|
1200
|
+
`owenloop start <defName>` sends `POST /api/start_run` and prints the new
|
|
1201
|
+
workflow id, its initial status, and the steps whose default crew was stamped or
|
|
1202
|
+
whose capability routes were validated. `--crew <name>` selects the crew for
|
|
1203
|
+
steps that declare no capability; capability-bearing steps continue to use
|
|
1204
|
+
their live hub bindings. `--title <text>` is display-only. Both `--crew` and
|
|
1205
|
+
`--title` require non-empty values; bare flags and `--crew=`/`--title=` are local
|
|
1206
|
+
usage errors before credential or network access. The command does not claim,
|
|
1207
|
+
dispatch, close, or otherwise drive work—the standing Shift discovers the run
|
|
1208
|
+
through its normal crew inbox.
|
|
1209
|
+
|
|
1210
|
+
**Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
|
|
1211
|
+
target in this order:
|
|
1212
|
+
|
|
1213
|
+
1. An explicit `--hub <origin>` always wins.
|
|
1214
|
+
2. `.owenloop/hub.json`, when present, is the project override.
|
|
1215
|
+
3. Global machine state supplies one unambiguous candidate:
|
|
1216
|
+
- with the file credential backend, exactly one origin containing a valid
|
|
1217
|
+
human-slot credential is selected automatically;
|
|
1218
|
+
- Keychain and external-command credential backends cannot enumerate their
|
|
1219
|
+
origins, so the validated `hubOrigin` in
|
|
1220
|
+
`$XDG_CONFIG_HOME/owenloop/settings.json` (or
|
|
1221
|
+
`~/.config/owenloop/settings.json`) is used, and the requested credential
|
|
1222
|
+
slot must exist there before the command proceeds.
|
|
1223
|
+
4. If nothing safe resolves, the command exits 2 without network or publication
|
|
1224
|
+
output effects.
|
|
1225
|
+
|
|
1226
|
+
More than one file-backed origin is also an exit-2 ambiguity: the error lists
|
|
1227
|
+
the origins in deterministic order and asks for `--hub <origin>` or
|
|
1228
|
+
`owenloop connect --hub <origin>`. A non-enumerable backend with no settings
|
|
1229
|
+
`hubOrigin` names the exact settings path and asks for the same explicit
|
|
1230
|
+
choice. `owenloop setup` populates that non-secret settings field. `OWENLOOP_HUB`
|
|
1231
|
+
and `DEFAULT_HUB` are intentionally excluded from the publishing ladder because
|
|
1232
|
+
an ambient guess can target the wrong hub organization; ambiguous or missing
|
|
1233
|
+
resolution fails closed instead of choosing one.
|
|
1234
|
+
|
|
495
1235
|
**Request timeouts.** Every hub call — OAuth discovery, client registration,
|
|
496
1236
|
code exchange, token refresh, `whoami`, the workflow list, and each push — is
|
|
497
1237
|
bounded by a 30s deadline; a stalled hub surfaces as a friendly `hub did not
|
|
@@ -567,28 +1307,66 @@ can read (only read) a stored credential through the same backend logic via the
|
|
|
567
1307
|
package's exported `readStoredCredential` — see
|
|
568
1308
|
[Embedding](embedding.md#whats-exported).
|
|
569
1309
|
|
|
1310
|
+
The macOS `security` adapter treats exit status 44 (`errSecItemNotFound`) as the
|
|
1311
|
+
only absence result: lookup returns no credential, and deletion succeeds
|
|
1312
|
+
idempotently (running the same deletion again changes nothing). Every other
|
|
1313
|
+
numeric status, signal termination, or command-start failure is a fatal backend
|
|
1314
|
+
error. Lookup and logout stop at that error; Owenloop neither reports success
|
|
1315
|
+
nor falls through to or deletes a file-store credential. Mapped errors name only
|
|
1316
|
+
the operation and backend failure class, never the service, account, credential,
|
|
1317
|
+
or stdin command.
|
|
1318
|
+
|
|
570
1319
|
**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
|
-
|
|
1320
|
+
token, or a `login`/`logout` that stores or deletes a slot — is serialized by the
|
|
1321
|
+
logical `credentials.lock` guard and the persistent SQLite lock database at
|
|
1322
|
+
`credentials.lock.sqlite-v2`, both siblings of `credentials.json` in the config
|
|
1323
|
+
dir (created for the keychain backend too, since the race the lock closes is
|
|
1324
|
+
backend-independent). The concern is a token-refresh
|
|
1325
|
+
race: two owenloop processes hitting an expiring OAuth token at once would each
|
|
1326
|
+
POST a refresh and each persist, and because refresh tokens rotate, the second
|
|
1327
|
+
write clobbers the first with a token whose refresh link is already spent —
|
|
1328
|
+
silently killing the credential. Under the lock a process re-reads the slot
|
|
1329
|
+
after acquiring it and, if another process already refreshed, **adopts** that
|
|
1330
|
+
fresh token instead of refreshing again — one network refresh, one write, no
|
|
1331
|
+
lost token. The lock matters only for OAuth refresh and store/delete; read paths
|
|
1332
|
+
and the external-command mode (which never writes the local store) do not take
|
|
1333
|
+
it.
|
|
1334
|
+
|
|
1335
|
+
SQLite owns exclusion through a `BEGIN IMMEDIATE` transaction tied to the live
|
|
1336
|
+
database connection. Release, normal process exit, and process crash close that
|
|
1337
|
+
connection and release the operating-system lock. Owenloop deliberately keeps
|
|
1338
|
+
the SQLite database path after release; Owenloop never deletes or replaces the
|
|
1339
|
+
path. A sibling `credentials.lock.owner.json` contains only diagnostic process
|
|
1340
|
+
metadata and does not determine ownership. If the lock cannot be acquired within
|
|
1341
|
+
the wait budget, the CLI fails loudly (`another owenloop process is using the
|
|
1342
|
+
credential store … — timed out waiting after Ns`) rather than refreshing
|
|
1343
|
+
unlocked. `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000) and
|
|
1344
|
+
`OWENLOOP_CRED_LOCK_POLL_MS` (default 100) override the wait behavior.
|
|
1345
|
+
`OWENLOOP_CRED_LOCK_STALE_MS` is accepted for compatibility but no longer causes
|
|
1346
|
+
pathname deletion. No token value appears in either lock file or the timeout
|
|
1347
|
+
message.
|
|
1348
|
+
|
|
1349
|
+
**Lock-file upgrade boundary.** The logical lock pathname, such as
|
|
1350
|
+
`credentials.lock`, remains a permanent, parseable JSON compatibility guard.
|
|
1351
|
+
The new SQLite lock database lives at `<logical-lock-path>.sqlite-v2`; for the
|
|
1352
|
+
credential store, that path is `credentials.lock.sqlite-v2`. A new client first
|
|
1353
|
+
holds SQLite's `BEGIN IMMEDIATE` transaction and then installs the guard at the
|
|
1354
|
+
old pathname with an exclusive create. The guard carries an impossible operating-
|
|
1355
|
+
system hostname, so a pre-SQLite client treats the guard as a live foreign-host
|
|
1356
|
+
owner and never age-reclaims it. An already-running old holder can release its
|
|
1357
|
+
ordinary JSON lock normally; the waiting new client then installs the guard and
|
|
1358
|
+
closes the one-way upgrade boundary. Old clients remain blocked after every new-
|
|
1359
|
+
client release or crash, while new clients continue to exclude one another
|
|
1360
|
+
through SQLite.
|
|
1361
|
+
|
|
1362
|
+
Release and crash cleanup close only the SQLite transaction. Owenloop never
|
|
1363
|
+
deletes, renames, or replaces either the permanent guard or the versioned SQLite
|
|
1364
|
+
database during normal lock lifecycle. A corrupt, partial, old-owner, or pre-
|
|
1365
|
+
boundary SQLite file already present at the logical legacy pathname fails closed:
|
|
1366
|
+
stop the relevant processes, verify that no old or pre-boundary process still
|
|
1367
|
+
owns that pathname, remove the legacy pathname manually, and let one upgraded
|
|
1368
|
+
client install the permanent guard. Routine stale-age or PID reclamation is no
|
|
1369
|
+
longer used, and `OWENLOOP_CRED_LOCK_STALE_MS` cannot weaken the boundary.
|
|
592
1370
|
|
|
593
1371
|
**Supplying the credential from your own tooling.** If your secrets live in a
|
|
594
1372
|
secret manager, or you run on a host with no keychain, set
|
|
@@ -630,14 +1408,35 @@ it — a `401` there means the credential is never written to disk. On success
|
|
|
630
1408
|
`orgId`, `identity`, and `email` when the hub returns one), read straight from
|
|
631
1409
|
`whoami`.
|
|
632
1410
|
|
|
1411
|
+
**Recording the hub for `owenloop mcp` (`~/.owenloop/config.json`).** After the
|
|
1412
|
+
credential above is verified and stored, `login` makes one more best-effort
|
|
1413
|
+
write: it records the hub origin it just authenticated against in
|
|
1414
|
+
`~/.owenloop/config.json` (`{"version": 1, "hub": "<origin>"}` — never a
|
|
1415
|
+
secret, just the origin). This file is separate from both the credential store
|
|
1416
|
+
above and from `owenloop setup`'s `~/.config/owenloop/settings.json`; its only
|
|
1417
|
+
reader is `owenloop mcp`'s [origin resolution](#choosing-the-hub-origin),
|
|
1418
|
+
which needs to know your hub without enumerating the credential store (the
|
|
1419
|
+
Keychain and external-command backends can't be listed at all — see below). A
|
|
1420
|
+
failure to write this file is a **warning** printed to stderr, never a fatal
|
|
1421
|
+
error and never blocking `login` itself, since the credential is already
|
|
1422
|
+
safely stored by the time this write is attempted. Logging into a second hub
|
|
1423
|
+
overwrites this file — "last login wins" — so if you routinely switch between
|
|
1424
|
+
hubs, pass `--hub` explicitly to `owenloop mcp` (or set `OWENLOOP_HUB`) rather
|
|
1425
|
+
than relying on whichever `login` ran most recently.
|
|
1426
|
+
|
|
633
1427
|
### `connect` — bind a project to a hub
|
|
634
1428
|
|
|
635
|
-
`owenloop connect`
|
|
636
|
-
|
|
637
|
-
/
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
1429
|
+
`owenloop connect` resolves a target through the publishing ladder, re-verifies
|
|
1430
|
+
the stored credential against `GET /api/whoami`, and writes
|
|
1431
|
+
`.owenloop/hub.json`. Run `login` first. With no `--hub`, an existing binding
|
|
1432
|
+
remains the target; an unbound project uses the unambiguous global fallback.
|
|
1433
|
+
An explicit `--hub` creates or replaces the project override, which is useful
|
|
1434
|
+
for multi-org or multi-hub repositories. `connect` is optional for the ordinary
|
|
1435
|
+
single-hub happy path, not a prerequisite for `push` or `publish`.
|
|
1436
|
+
|
|
1437
|
+
The JSON reports the same org/identity fields as `login`; re-connecting to the
|
|
1438
|
+
**same** origin reports no `switchedFrom`, switching to a **different** hub
|
|
1439
|
+
reports `switchedFrom: <old origin>` and rebinds the project to the new one.
|
|
641
1440
|
|
|
642
1441
|
A symlinked project `.owenloop` directory is refused with a clear error rather
|
|
643
1442
|
than followed: a hostile checkout cannot ship `.owenloop -> /elsewhere` to
|
|
@@ -647,16 +1446,40 @@ guarantee). The same refusal covers the default `state.db` FILE (and its SQLite
|
|
|
647
1446
|
file would otherwise redirect the store's writes, since SQLite follows file
|
|
648
1447
|
symlinks.
|
|
649
1448
|
|
|
650
|
-
### `push` — publish local defs to the
|
|
1449
|
+
### `push` — publish local defs to the resolved hub
|
|
651
1450
|
|
|
652
1451
|
`owenloop push [<defName>...]` publishes the project's workflow defs (all of
|
|
653
|
-
them, or just the named ones) to the hub
|
|
1452
|
+
them, or just the named ones) to the hub selected by the publishing ladder.
|
|
1453
|
+
`--hub` overrides a project binding for that invocation without rewriting it;
|
|
1454
|
+
otherwise the project override wins over global state. An unbound project with
|
|
1455
|
+
one file-backed human credential therefore needs no setup step. Ambiguous or
|
|
1456
|
+
missing candidates exit 2 as described above, and `OWENLOOP_HUB`/
|
|
1457
|
+
`DEFAULT_HUB` never participate. `push` never writes a project binding. It
|
|
654
1458
|
reuses the **exact** all-or-nothing validation gate `add` uses — lint, validate,
|
|
655
1459
|
and a bounded `check` — across every selected def before a single byte is sent;
|
|
656
1460
|
any definite defect aborts the whole push. stdout is machine-parseable JSON;
|
|
657
1461
|
the human-readable diff (`+ new`, `~ changed`, `= unchanged`, `! failed`) goes
|
|
658
1462
|
to stderr.
|
|
659
1463
|
|
|
1464
|
+
`owenloop push --bundle <bundle.wnlp> [<defName>...]` is the executable,
|
|
1465
|
+
bundle-backed form. The exact archive is inspected and becomes the definition
|
|
1466
|
+
source; checkout files are ignored. Push requires exactly one adjacent
|
|
1467
|
+
publication sidecar produced by `owenloop publish` (`.dsse` or `.unsigned`),
|
|
1468
|
+
accepts an optional `.origin.dsse`, uploads those content-addressed objects,
|
|
1469
|
+
then calls `create_workflow` with the archive's canonical digest. This is what
|
|
1470
|
+
makes the hub stamp reference orders with a digest that execution hosts can
|
|
1471
|
+
resolve from their installed bundle store. Because a reference order identifies
|
|
1472
|
+
its executable instructions only by bundle digest plus step name, every workflow
|
|
1473
|
+
definition in the complete archive must use distinct step names. `push --bundle`
|
|
1474
|
+
refuses an archive when two definitions share a step name, even when positional
|
|
1475
|
+
arguments select only one of those definitions; the refusal happens before any
|
|
1476
|
+
bundle, evidence, or workflow-version write. Bundle mode conservatively sends
|
|
1477
|
+
each selected `create_workflow` request even when its YAML hash is unchanged,
|
|
1478
|
+
because the workflow listing does not expose the latest bundle identity; the
|
|
1479
|
+
hub's `(yaml, bundle digest)` idempotency decides whether to version-forward or
|
|
1480
|
+
return `noop`. `--dry-run` validates the archive and sidecars and performs only
|
|
1481
|
+
the read-only server diff—no bundle, sidecar, or definition is uploaded.
|
|
1482
|
+
|
|
660
1483
|
**Idempotency is server-side truth, not a client ledger.** `push` fetches the
|
|
661
1484
|
hub's own view of every def (`GET /api/workflows`, which reports each def's
|
|
662
1485
|
`hash`) and diffs local content against it directly — there is no
|
|
@@ -678,6 +1501,15 @@ batch: the current def is recorded as `failed`, the not-yet-attempted remainder
|
|
|
678
1501
|
is reported under a `skipped` output key, and any `Retry-After` the hub sent is
|
|
679
1502
|
surfaced in the error.
|
|
680
1503
|
|
|
1504
|
+
Selected definitions are published in topological `calls:` order. If a selected
|
|
1505
|
+
dependency fails or is skipped, Owenloop sends no `create_workflow` request for
|
|
1506
|
+
its selected dependents; each dependent is added to `skipped`, names its failed
|
|
1507
|
+
or skipped dependencies in sorted order, and becomes unsuccessful so the skip
|
|
1508
|
+
propagates transitively. Independent selected definitions continue publishing.
|
|
1509
|
+
A locally `unchanged` dependency and a server `noop` dependency both count as
|
|
1510
|
+
successful, so either result permits the dependent to publish. Dependency
|
|
1511
|
+
matching covers bare names and same-package-qualified names in a bundle.
|
|
1512
|
+
|
|
681
1513
|
The def hash is computed by re-parsing the raw YAML with no checkout-specific
|
|
682
1514
|
`baseDir` — the same canonicalization the hub applies — so it's portable
|
|
683
1515
|
across checkouts and machines by construction: a fresh clone at a different
|
|
@@ -698,6 +1530,59 @@ def isn't round-trippable. A def using `bodyFile:` is refused the same way
|
|
|
698
1530
|
resolve the external file against once the YAML leaves this machine. Inline
|
|
699
1531
|
both before pushing.
|
|
700
1532
|
|
|
1533
|
+
### `publish` — pack and publish a workflow bundle
|
|
1534
|
+
|
|
1535
|
+
```text
|
|
1536
|
+
owenloop publish <source-dir> [--output <bundle.wnlp>] [--source <json>] [--unsigned] [--hub <origin>]
|
|
1537
|
+
```
|
|
1538
|
+
|
|
1539
|
+
`publish` is separate from both [`bundle pack`](#bundles) and [`push`](#push--publish-local-defs-to-the-resolved-hub). It packs one source directory with the same deterministic `packBundle` implementation as `bundle pack`, then publishes the bundle beside a local publication sidecar and, optionally, a signed origin sidecar. A project binding is optional; when present it supplies the project-specific author-key origin unless `--hub` overrides it.
|
|
1540
|
+
|
|
1541
|
+
The author-key origin comes from the same publishing ladder as `connect` and
|
|
1542
|
+
`push`: `--hub` wins, a project binding overrides global state, one file-backed
|
|
1543
|
+
human origin resolves automatically, and a non-enumerable backend uses the
|
|
1544
|
+
validated execution-settings `hubOrigin` only when the human credential exists.
|
|
1545
|
+
An ambiguous or absent candidate exits 2 before signing, packing, or output
|
|
1546
|
+
writes. `publish` never writes `.owenloop/hub.json`, consults `OWENLOOP_HUB`, or
|
|
1547
|
+
guesses `DEFAULT_HUB`.
|
|
1548
|
+
|
|
1549
|
+
Signed publication is the default. In signed mode, `publish` requires the human principal signing key for the resolved hub. Run `owenloop setup` before the first signed publication. `publish` never creates or repairs a signing key: an older key store that already contains the key but lacks the non-secret `<hash>.ref` pointer must be repaired by a setup run, whose `ensure` step backfills the pointer without regenerating or replacing the private key. If the author-key reference or key record is missing, `publish` fails and suggests `owenloop setup` or the explicit unsigned mode; the command does not silently downgrade to unsigned output.
|
|
1550
|
+
|
|
1551
|
+
In signed mode, `publish` confirms the existing key and probes the signer before `packBundle` runs, then signs the publication record before any bundle or sidecar is written. A signing failure therefore leaves no half-published artifact. The signature covers a DSSE publication record whose `digest` is the lowercase SHA-256 digest of the uncompressed canonical tar inside the `.wnlp` file. When `--source <json>` is supplied, the command signs a separate origin record with the same signer and digest, then writes `<output>.origin.dsse` beside the publication sidecar. The remote hub is not involved in this local signing operation and never produces or completes either signature.
|
|
1552
|
+
|
|
1553
|
+
`--source` is signer-supplied provenance, not a hub-derived label. The JSON value must be one of these closed forms:
|
|
1554
|
+
|
|
1555
|
+
- `{"kind":"git","repo":"<repo>","commit":"<40- or 64-hex commit SHA>"}`;
|
|
1556
|
+
- `{"kind":"console","user":"<authoring user>"}`, which requires a client-side signing ceremony; or
|
|
1557
|
+
- `{"kind":"agent","agent":"<agent identity>","session":"<session>"}`.
|
|
1558
|
+
|
|
1559
|
+
The origin record is part of the signed content. The hub or another relay stores and relays the signed record but cannot write, derive, default, or stamp an origin value. `attesterKeyId` in the record is only a candidate-selection hint; verification cross-checks the hint against the signer that produced the verified signature. `--source` cannot be combined with `--unsigned`. The CLI currently rejects the `console` form because that form requires a client-side signing ceremony rather than this command's local signing path.
|
|
1560
|
+
|
|
1561
|
+
`--unsigned` is an explicit opt-in. Unsigned mode still packs the canonical bundle, but writes an unauthenticated author-intent marker rather than a DSSE envelope. Anyone can write such a marker; consumers must treat missing and unverifiable signatures as unsigned regardless of whether the marker is present. Publication and unsigned sidecars are mutually exclusive:
|
|
1562
|
+
|
|
1563
|
+
- signed mode writes `<output>.wnlp.dsse` and removes a stale `<output>.wnlp.unsigned`;
|
|
1564
|
+
- `--unsigned` writes `<output>.wnlp.unsigned` and removes a stale `<output>.wnlp.dsse`.
|
|
1565
|
+
|
|
1566
|
+
A signed publish without `--source` removes a stale `<output>.origin.dsse`. Unsigned mode also removes a stale origin sidecar because an unsigned origin would only be an unsigned label.
|
|
1567
|
+
|
|
1568
|
+
The output defaults to `<package-name>-<version>.wnlp` next to the source directory. `--output` must name a path outside the source directory. Existing regular output and sidecar files may be replaced; directories and other non-regular paths are rejected.
|
|
1569
|
+
|
|
1570
|
+
Successful invocations print exactly one machine-readable JSON object to stdout. Signed output without an origin has this shape:
|
|
1571
|
+
|
|
1572
|
+
```json
|
|
1573
|
+
{
|
|
1574
|
+
"ok": true,
|
|
1575
|
+
"bundle": "/absolute/path/report-1.2.0.wnlp",
|
|
1576
|
+
"digest": "<64 lowercase hex characters>",
|
|
1577
|
+
"name": "report",
|
|
1578
|
+
"version": "1.2.0",
|
|
1579
|
+
"signed": true,
|
|
1580
|
+
"envelope": "/absolute/path/report-1.2.0.wnlp.dsse"
|
|
1581
|
+
}
|
|
1582
|
+
```
|
|
1583
|
+
|
|
1584
|
+
When `--source` is supplied, signed output also includes `"origin": "/absolute/path/report-1.2.0.wnlp.origin.dsse"`. Unsigned output has the same `ok`, `bundle`, `digest`, `name`, and `version` fields, with `"signed": false` and `"marker": "/absolute/path/report-1.2.0.wnlp.unsigned"` instead of `envelope`. Diagnostics and failures go to stderr and exit nonzero. `bundle pack` and `push` are unchanged by this command.
|
|
1585
|
+
|
|
701
1586
|
Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
|
|
702
1587
|
device-code grant remain recorded follow-ups on the service, not gaps in the
|
|
703
1588
|
CLI.
|
|
@@ -733,10 +1618,22 @@ minting on the wrong org is not undone by a retry:
|
|
|
733
1618
|
|
|
734
1619
|
Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
|
|
735
1620
|
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
|
-
|
|
1621
|
+
production hub while you're logged into a dev one. This is deliberately
|
|
1622
|
+
stricter than [`owenloop mcp`'s origin resolution](#choosing-the-hub-origin):
|
|
1623
|
+
`mcp` exposes both reads and writes, including `create_agent` (which mints and
|
|
1624
|
+
stores an agent token), `create_workflow`, `publish_event`, `submit`,
|
|
1625
|
+
`stage_enrollment`, and crew mutations. The default remains acceptable for
|
|
1626
|
+
`mcp` because each tool call authenticates against the resolved origin; when no
|
|
1627
|
+
human credential exists there, the existing `loginHint` surfaces the origin
|
|
1628
|
+
and asks for `owenloop login --hub <origin>` before the tool-specific action
|
|
1629
|
+
runs. If a credential does exist at an unintended origin and `create_agent`
|
|
1630
|
+
mints there, the stored agent token is revocable; `--hub` and `OWENLOOP_HUB`
|
|
1631
|
+
remain available when the operator wants to avoid inference. `agent new`
|
|
1632
|
+
**mints** a new credential directly, a side effect a retry cannot undo, so it
|
|
1633
|
+
stops at step 3 instead of ever guessing. Note that hub enumeration itself is
|
|
1634
|
+
**file-store only**: the keychain and the external-command backend cannot list
|
|
1635
|
+
their entries, so on such a machine step 2 cannot enumerate the store and you
|
|
1636
|
+
must pass `--hub`.
|
|
740
1637
|
|
|
741
1638
|
**`--crews <a,b>`.** A comma-separated list of crew names the token is granted
|
|
742
1639
|
on (trimmed, empties dropped). Omit the flag to let the hub default the token to
|
|
@@ -1062,16 +1959,19 @@ lines (the tolerant-false notices, the transfer summary) go to stderr only.
|
|
|
1062
1959
|
|
|
1063
1960
|
## `setup` — onboard a machine
|
|
1064
1961
|
|
|
1065
|
-
`owenloop setup` is the one-shot onboarding command. It runs
|
|
1962
|
+
`owenloop setup` is the one-shot onboarding command. It runs seven ordered steps.
|
|
1066
1963
|
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
|
-
|
|
1964
|
+
rekey and store a Scoped Identity credential, ensure the three principal
|
|
1965
|
+
signing keys, relay a signed machine enrollment grant, and write only
|
|
1966
|
+
`hubOrigin` in the execution settings file while preserving its other keys.
|
|
1967
|
+
The plugin step probes and, when needed, converges the bundled `owenloop` plugin
|
|
1968
|
+
for each available harness: Claude Code and Codex. Plugin convergence is
|
|
1969
|
+
non-fatal and setup continues when a harness is missing, the bundled marketplace
|
|
1970
|
+
root is unavailable, or a plugin command fails. A second run with the expected
|
|
1971
|
+
plugin version already installed performs no plugin writes. The steps:
|
|
1072
1972
|
|
|
1073
1973
|
1. **inspect** — read-only report of what's already present (human credential,
|
|
1074
|
-
execution settings, `claude` on PATH, agent slots). No writes.
|
|
1974
|
+
execution settings, `claude` and `codex` on PATH, agent slots). No writes.
|
|
1075
1975
|
2. **human login** — verify the stored **human** credential, or run the same
|
|
1076
1976
|
loopback-OAuth browser flow as `owenloop login` when none is present or it no
|
|
1077
1977
|
longer verifies. This is the gate that makes step 3's mint/rekey legal.
|
|
@@ -1079,17 +1979,28 @@ installs the plugin. The steps:
|
|
|
1079
1979
|
hub and reuse it; otherwise **mint** a new Scoped Identity or **rekey**
|
|
1080
1980
|
(replace the credential of) an existing one. How the target is chosen is
|
|
1081
1981
|
[below](#choosing-the-scoped-identity-flow-a-vs-flow-b).
|
|
1082
|
-
4. **
|
|
1982
|
+
4. **signing keys** — ensure an Ed25519 signing key for each of the three local
|
|
1983
|
+
principals, in order: human, machine, agent. Details
|
|
1984
|
+
[below](#signing-keys-step-4). After key convergence, setup performs the
|
|
1985
|
+
enrollment relay sub-step described below.
|
|
1986
|
+
5. **execution settings** — write only `hubOrigin` into the execution settings
|
|
1083
1987
|
file so the local Step Agent talks to this hub, preserving every other key
|
|
1084
1988
|
(skipped when `hubOrigin` already matches).
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1989
|
+
6. **plugin** — probe and converge the bundled `owenloop` plugin separately
|
|
1990
|
+
for Claude Code and Codex. When the installed plugin is missing or its
|
|
1991
|
+
version differs from the CLI package, setup adds the bundled marketplace
|
|
1992
|
+
when needed and installs or updates the plugin. Claude Code uses
|
|
1993
|
+
`claude plugin install` for a fresh install and `claude plugin update` for
|
|
1994
|
+
an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
|
|
1995
|
+
fresh installs and upgrades; setup does not call
|
|
1996
|
+
`codex plugin marketplace upgrade`, which applies only to Git marketplaces.
|
|
1997
|
+
**Non-fatal:** a missing harness or failed convergence is reported as
|
|
1998
|
+
`noted` and never fails setup. If the bundled marketplace root is
|
|
1999
|
+
unavailable, setup prints manual commands instead.
|
|
2000
|
+
7. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
|
|
1090
2001
|
the same surfaces, whose result becomes setup's exit code.
|
|
1091
2002
|
|
|
1092
|
-
Progress lines (the `[n/
|
|
2003
|
+
Progress lines (the `[n/7]` headers and `✓`/`✗` marks) go to **stderr**; the
|
|
1093
2004
|
final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
|
|
1094
2005
|
**stdout**.
|
|
1095
2006
|
|
|
@@ -1128,6 +2039,88 @@ is a usage error, because rekeying preserves the Scoped Identity's existing scop
|
|
|
1128
2039
|
new Scoped Identity to change scopes). `setup` has no `--shift` shorthand — spell the
|
|
1129
2040
|
scopes out with `--scopes work,run`.
|
|
1130
2041
|
|
|
2042
|
+
### Signing keys (step 4)
|
|
2043
|
+
|
|
2044
|
+
Step 4 ensures one Ed25519 signing key per local principal — human, machine,
|
|
2045
|
+
agent — keyed by `{ hub origin, kind, principal id }`. It is **idempotent**:
|
|
2046
|
+
an existing key reports `existing` and is never regenerated or rewritten. A
|
|
2047
|
+
second full setup run performs zero key writes.
|
|
2048
|
+
|
|
2049
|
+
**Storage backends.** The key record goes to the macOS Keychain
|
|
2050
|
+
(`security`), to Linux libsecret (`secret-tool`) when that binary is on
|
|
2051
|
+
`PATH`, and otherwise to a `0600` file under `$HOME/.owenloop/keys/` (both
|
|
2052
|
+
parent directories forced `0700`, symlinks refused). One backend is selected
|
|
2053
|
+
once and a failure is a hard error — there is never a fallback to another
|
|
2054
|
+
backend, because a fallback could mint a second, different key for the same
|
|
2055
|
+
principal. `OWENLOOP_NO_KEYCHAIN=1` forces the file backend. Private bytes
|
|
2056
|
+
never appear on argv or in setup output.
|
|
2057
|
+
|
|
2058
|
+
**`--reuse-ssh-key <path>`** records your own existing Ed25519 SSH key for the
|
|
2059
|
+
**human** principal instead of generating one. The candidate is validated with
|
|
2060
|
+
a non-secret sign/verify challenge before anything is recorded, and only its
|
|
2061
|
+
canonical path + public key are stored — the private key is never copied. It
|
|
2062
|
+
applies to the human key only (machine and agent always get generated keys),
|
|
2063
|
+
and it is a **hard conflict** when a human key already exists: setup keeps the
|
|
2064
|
+
existing key and errors rather than rotating (rotation is not part of this
|
|
2065
|
+
work package). A nonexistent path fails up front, before any browser opens.
|
|
2066
|
+
|
|
2067
|
+
**Secret-output guarantee.** Step 4 prints only `kind state (backend)` — e.g.
|
|
2068
|
+
`✓ signing keys: human created (macos-security), machine created (file), agent
|
|
2069
|
+
existing (macos-security)` — never key bytes, fingerprints, or secret-store
|
|
2070
|
+
values. The full storage and signing model is in
|
|
2071
|
+
[Signing and key storage](crypto.md).
|
|
2072
|
+
|
|
2073
|
+
### Machine enrollment relay
|
|
2074
|
+
|
|
2075
|
+
After the three keys are ensured, setup tries to register the machine public key
|
|
2076
|
+
with the hub. The relay is deliberately subordinate to local key convergence:
|
|
2077
|
+
|
|
2078
|
+
1. Read-only inspect the human signing key. If no human signing key is present,
|
|
2079
|
+
setup records `skipped` and performs no enrollment request.
|
|
2080
|
+
2. `GET /api/enrollments` with the human credential. If the hub is unavailable,
|
|
2081
|
+
returns an unsupported status such as `404`, returns `500`, or returns an
|
|
2082
|
+
unusable response, setup records `noted` and continues.
|
|
2083
|
+
3. If the machine public-key fingerprint is already present, setup records
|
|
2084
|
+
`skipped` and does not sign or POST a duplicate.
|
|
2085
|
+
4. Otherwise, the human signing key signs an `EnrollmentGrantRecord` locally.
|
|
2086
|
+
The grant names the machine principal `{ kind: "machine", id: "local" }`,
|
|
2087
|
+
uses the default least-privilege machine scope, and sets `grantedBy` to the
|
|
2088
|
+
human public-key fingerprint.
|
|
2089
|
+
5. `POST /api/enrollments` receives only `{ envelope }`, where `envelope` is the
|
|
2090
|
+
signed DSSE enrollment grant. The machine private key, human private key
|
|
2091
|
+
bytes, key-store values, and private-key paths never enter the request body.
|
|
2092
|
+
HTTP `409` means already registered and becomes `skipped`; other transport or
|
|
2093
|
+
hub failures become `noted` and do not undo local key creation.
|
|
2094
|
+
|
|
2095
|
+
The relay is idempotent (repeating the operation after the first successful
|
|
2096
|
+
registration changes nothing) and the hub is only a storage/relay endpoint. The
|
|
2097
|
+
hub does not create, sign, or endorse the grant.
|
|
2098
|
+
|
|
2099
|
+
## `enrollments` — inspect machine enrollment
|
|
2100
|
+
|
|
2101
|
+
`owenloop enrollments [--hub <url>]` fetches the hub's relayed DSSE envelopes and
|
|
2102
|
+
verifies each entry locally. The command is read-only: it does not call key
|
|
2103
|
+
creation, does not sign a grant, and does not POST to the hub. The command uses
|
|
2104
|
+
the local `allowed_signers` trust root when one is configured.
|
|
2105
|
+
|
|
2106
|
+
The command prints `{ ok, hub, enrollments }` on stdout. Each entry has one of
|
|
2107
|
+
four verdicts:
|
|
2108
|
+
|
|
2109
|
+
| verdict | meaning |
|
|
2110
|
+
|---|---|
|
|
2111
|
+
| `enrolled` | the grant payload and DSSE signature are valid, the signer is in the local `allowed_signers` root, and an enrollment-chain validator approved the grant |
|
|
2112
|
+
| `unenrolled` | no envelope was supplied for the roster entry |
|
|
2113
|
+
| `unverifiable` | verification cannot establish trust, including a missing `allowed_signers` root or the D1 fail-closed state where no chain validator is installed |
|
|
2114
|
+
| `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result is invalid |
|
|
2115
|
+
|
|
2116
|
+
WP-D1 intentionally does not install an enrollment-chain validator. Therefore a
|
|
2117
|
+
well-formed, correctly signed D1 grant is reported as `unverifiable` until WP-D4
|
|
2118
|
+
installs the validator. This prevents a signature from being mistaken for proof
|
|
2119
|
+
that the grantor is enrolled.
|
|
2120
|
+
|
|
2121
|
+
A missing human credential is exit `3`; hub, malformed-response, and other
|
|
2122
|
+
runtime failures are exit `1`; successful classification is exit `0`.
|
|
2123
|
+
|
|
1131
2124
|
### Hub resolution differs from `agent new`
|
|
1132
2125
|
|
|
1133
2126
|
`setup` (and `doctor`) resolve the target hub like `agent new` with **one**
|
|
@@ -1187,22 +2180,30 @@ The checks, in order:
|
|
|
1187
2180
|
| 3 | agent slot | an `agent:<name>` credential is stored | yes |
|
|
1188
2181
|
| 4 | agent plane | that agent credential verifies live against the hub | yes |
|
|
1189
2182
|
| 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) |
|
|
2183
|
+
| 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
|
|
2184
|
+
| 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
|
|
2185
|
+
|
|
2186
|
+
The plugin checks also report the detected harness CLI version. An installed
|
|
2187
|
+
plugin whose version cannot be parsed is reported as `version unknown` and is
|
|
2188
|
+
not treated as a failure. A parsed plugin version that differs from the
|
|
2189
|
+
package version is reported as version skew with the remedy `run owenloop
|
|
2190
|
+
setup`. A missing harness reports that the harness is not on `PATH`; a missing
|
|
2191
|
+
plugin reports the harness-specific marketplace and install command.
|
|
1191
2192
|
|
|
1192
2193
|
Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
|
|
1193
2194
|
<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.
|
|
2195
|
+
machine with no working human credential still renders the later checks,
|
|
2196
|
+
degrading honestly rather than dropping them.
|
|
1196
2197
|
|
|
1197
|
-
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise.
|
|
1198
|
-
plugin
|
|
1199
|
-
marketplace is unpublished.
|
|
2198
|
+
**Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. Both
|
|
2199
|
+
plugin checks (6–7) are *rendered* but do not affect the exit code.
|
|
1200
2200
|
|
|
1201
2201
|
## `mcp` — stdio control-plane server for MCP hosts
|
|
1202
2202
|
|
|
1203
2203
|
`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).
|
|
2204
|
+
plane** to a local MCP host (Claude Code, Codex, or any client that speaks MCP
|
|
2205
|
+
over stdio). The shipped Claude Code and Codex plugins launch this command from
|
|
2206
|
+
`PATH`. This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
|
|
1206
2207
|
subprocess — **you do not run it yourself at a prompt**. It reads
|
|
1207
2208
|
newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
|
|
1208
2209
|
authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
|
|
@@ -1215,29 +2216,77 @@ loopback listener. If no human credential is stored, a tool call returns an
|
|
|
1215
2216
|
error telling you to run `owenloop login --hub <origin>` in a terminal and retry
|
|
1216
2217
|
(see [Authentication and secrets](#authentication-and-secrets) below).
|
|
1217
2218
|
|
|
2219
|
+
### Plugin/CLI version alignment
|
|
2220
|
+
|
|
2221
|
+
The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
|
|
2222
|
+
carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
|
|
2223
|
+
server compares that expected version with its own package version on every
|
|
2224
|
+
recognized `tools/call`. The comparison is strict equality: a mismatch returns
|
|
2225
|
+
a tool error that names both versions and says `Run: owenloop setup`. The
|
|
2226
|
+
server does not reject the MCP startup handshake, so the diagnostic reaches the
|
|
2227
|
+
model and the human instead of appearing only as a transport-closed error.
|
|
2228
|
+
|
|
2229
|
+
Each plugin also declares a `SessionStart` hook. The hook reads the plugin
|
|
2230
|
+
manifest version, sends an MCP `initialize` request to `owenloop mcp` using a
|
|
2231
|
+
non-routable probe origin, and reads `serverInfo.version`; the root CLI has no
|
|
2232
|
+
supported `owenloop --version` flag. The hook reports a missing CLI, an
|
|
2233
|
+
unparseable version, or a mismatch to stderr and always exits successfully, so
|
|
2234
|
+
a diagnostic cannot block session startup. Claude Code runs the hook after
|
|
2235
|
+
installation. Codex runs plugin hooks only after the user approves them in
|
|
2236
|
+
`/hooks`; if the user does not approve Codex hooks, the always-on MCP check
|
|
2237
|
+
still catches a version mismatch when a tool call is made.
|
|
2238
|
+
|
|
2239
|
+
If the versions differ, run `owenloop setup` and follow the printed plugin
|
|
2240
|
+
installation instructions before retrying the MCP tool call.
|
|
2241
|
+
|
|
1218
2242
|
### Choosing the hub origin
|
|
1219
2243
|
|
|
1220
2244
|
`owenloop mcp` binds to exactly one hub origin, resolved in this order:
|
|
1221
2245
|
|
|
1222
2246
|
1. `--hub <url>` flag.
|
|
1223
2247
|
2. `OWENLOOP_HUB` env var.
|
|
1224
|
-
3.
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
2248
|
+
3. `~/.owenloop/config.json` — see below.
|
|
2249
|
+
4. If the **file** credential backend holds exactly ONE hub with a valid
|
|
2250
|
+
`human` credential, that hub is used (kept for back-compat with installs
|
|
2251
|
+
from before step 3 existed).
|
|
2252
|
+
5. The built-in **default hub**, `https://api.owenloop.com`.
|
|
2253
|
+
|
|
2254
|
+
Every inference rung after the first two **falls through silently** rather
|
|
2255
|
+
than stopping the server: a missing or corrupt config file, a `hub` value in
|
|
2256
|
+
it that doesn't parse as a valid origin, an unenumerable credential store
|
|
2257
|
+
(macOS Keychain or an external credential command — only the file backend can
|
|
2258
|
+
be listed at all), zero stored hubs, and more than one stored hub all just
|
|
2259
|
+
move on to the next rung. `owenloop mcp` never exits for an inferred-origin
|
|
2260
|
+
reason — this is deliberate: it is a long-running process spawned
|
|
2261
|
+
automatically by an MCP host on every session start, not a one-shot command a
|
|
2262
|
+
human is watching, so a hard stop here would silently break the plugin on any
|
|
2263
|
+
machine using the Keychain backend (the macOS default) unless the operator
|
|
2264
|
+
remembered to set `--hub` or `OWENLOOP_HUB` first.
|
|
2265
|
+
|
|
2266
|
+
The MCP surface is not read-only. It includes `create_agent`, which mints and
|
|
2267
|
+
stores a new agent token, plus state-changing tools such as `create_workflow`,
|
|
2268
|
+
`publish_event`, `submit`, `stage_enrollment`, and the crew mutations. The
|
|
2269
|
+
server still authenticates each tool call against the resolved origin. When no
|
|
2270
|
+
human credential exists at that origin, the first authenticated tool call
|
|
2271
|
+
returns `loginHint` with the origin and asks for `owenloop login --hub
|
|
2272
|
+
<origin>` before the tool-specific action runs. If a credential does exist at
|
|
2273
|
+
an unintended origin and `create_agent` mints there, the stored agent token is
|
|
2274
|
+
revocable; explicit `--hub` and `OWENLOOP_HUB` remain available to avoid
|
|
2275
|
+
inference. Contrast this with [`agent new`](#agent-new--mint-an-agent-token-into-a-slot),
|
|
2276
|
+
which **mints** a new credential directly and therefore stops rather than
|
|
2277
|
+
ever guessing — a wrong guess there is a side effect a retry cannot undo.
|
|
2278
|
+
|
|
2279
|
+
**`~/.owenloop/config.json`** is written by
|
|
2280
|
+
[`login`](#login--authenticate-the-cli-against-a-hub): a small, non-secret
|
|
2281
|
+
JSON file (`{"version": 1, "hub": "<origin>"}`) recording the hub `login` most
|
|
2282
|
+
recently authenticated against. It exists specifically so `mcp` can learn
|
|
2283
|
+
your hub without enumerating the credential store — see `login`'s own section
|
|
2284
|
+
for exactly when it's written and what happens if the write fails.
|
|
2285
|
+
|
|
2286
|
+
A malformed `--hub`/`OWENLOOP_HUB` value is still a normal exit-`1` error,
|
|
2287
|
+
like every other command — an explicit bad value is reported, never silently
|
|
2288
|
+
skipped, precisely because rungs 1–2 come from something the operator typed
|
|
2289
|
+
or set, not from inference.
|
|
1241
2290
|
|
|
1242
2291
|
### Tools
|
|
1243
2292
|
|
|
@@ -1341,7 +2390,7 @@ interactively.
|
|
|
1341
2390
|
|
|
1342
2391
|
| variable | effect |
|
|
1343
2392
|
|---|---|
|
|
1344
|
-
| `OWENLOOP_HUB` |
|
|
2393
|
+
| `OWENLOOP_HUB` | development override for the hub origin (rung 2, above `~/.owenloop/config.json`) |
|
|
1345
2394
|
| `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
|
|
1346
2395
|
| `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
|
|
1347
2396
|
| `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
|
|
@@ -1453,8 +2502,13 @@ non-zero exit as a failure, not a success.
|
|
|
1453
2502
|
|
|
1454
2503
|
## What a job looks like
|
|
1455
2504
|
|
|
1456
|
-
`tick` returns `{ workflow, orders, reaped }`. Each order is
|
|
1457
|
-
|
|
2505
|
+
`tick` returns `{ workflow, orders, reaped }`. Each order is a **reference
|
|
2506
|
+
packet**: it carries the routing fields and run-time context for the job — the
|
|
2507
|
+
run id, the captured input values, the owed outputs with their reason threads
|
|
2508
|
+
— plus a `defDigest` that names *which definition snapshot* holds the authored
|
|
2509
|
+
instructions. The instructions themselves (the step's `body:` prompt, any
|
|
2510
|
+
`command:` text) are **not** on the order, and `tick`/`order` never print
|
|
2511
|
+
them.
|
|
1458
2512
|
|
|
1459
2513
|
```jsonc
|
|
1460
2514
|
{
|
|
@@ -1462,22 +2516,42 @@ a Step Agent needs nothing else to do the work:
|
|
|
1462
2516
|
"workflow": "wf_…", // the instance this order belongs to — see deep tick below
|
|
1463
2517
|
"step": "builder", // which step this job is for
|
|
1464
2518
|
"key": "", // map jobs carry the element key + index
|
|
2519
|
+
"defDigest": "9f2c…", // identifies the definition snapshot to resolve instructions from
|
|
1465
2520
|
"inputs": ["plan"],
|
|
1466
2521
|
"outputs": ["pr"],
|
|
1467
|
-
"
|
|
2522
|
+
"worker": "command", // the authored step's executor:, mapped verbatim (absent = 'agent')
|
|
1468
2523
|
"consumes": { "plan": { /* the accepted input value */ } },
|
|
1469
2524
|
"owes": [ // the feedback channel
|
|
1470
|
-
{ "path": "pr", "
|
|
2525
|
+
{ "path": "pr", "judgmentRejects": 2, "schemaRejects": 0,
|
|
1471
2526
|
"reasons": [ { "action": "reject", "kind": "judgment", "by": "reviewer",
|
|
1472
2527
|
"text": "tests are missing", "at": 0 } ] }
|
|
1473
2528
|
]
|
|
1474
2529
|
}
|
|
1475
2530
|
```
|
|
1476
2531
|
|
|
1477
|
-
A
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
2532
|
+
A worker first **resolves the reference**: the `(defDigest, step, key)`
|
|
2533
|
+
boundary maps the order to the exact authored instructions from the worker's
|
|
2534
|
+
trusted local definition source — the same resolver the embedded engine and
|
|
2535
|
+
the CLI use. Resolution returns the authored `prompt` (with
|
|
2536
|
+
`${WORKFLOW}`/`${RUN}`/`${STEP}`/`${KEY}`/`${INDEX}`/`${MAX_ATTEMPTS}`
|
|
2537
|
+
materialized), the authored `command` if the step has one, and nothing
|
|
2538
|
+
fabricated. If the worker's source does not know the digest — the definition
|
|
2539
|
+
was never delivered, or the current on-disk definition no longer matches the
|
|
2540
|
+
pinned digest — resolution raises `UnknownDefDigestError`. If the digest is
|
|
2541
|
+
known but the referenced step is absent, resolution raises the distinct
|
|
2542
|
+
`UnknownInstructionError` and identifies the digest, step, and key. The worker
|
|
2543
|
+
must refuse either malformed reference rather than guess instructions by step
|
|
2544
|
+
name or fetch unverified text. Once resolved, the worker reads the resolved
|
|
2545
|
+
prompt + `consumes` + `owes`, does the work, reports with `green` (or
|
|
2546
|
+
`emit`/`seal` for collections), then `close`s the job. The reject counts in
|
|
2547
|
+
`owes[]` let a workflow escalate on its own — e.g. switch to a stronger model
|
|
2548
|
+
after two rejections — before the engine stalls the step.
|
|
2549
|
+
|
|
2550
|
+
Static authored text (prompts, commands) travels by digest reference; dynamic
|
|
2551
|
+
data — `consumes` values and the rejection `reasons` threads — stays on the
|
|
2552
|
+
order because it exists only for this run. A remote coordinator or transport
|
|
2553
|
+
that relays these packets never sees authored instruction text and never needs
|
|
2554
|
+
to: instructions resolve at the worker, from a source the worker trusts.
|
|
1481
2555
|
|
|
1482
2556
|
**Deep tick and `order.workflow`.** `tick <wf>` is **deep by default**: it ticks
|
|
1483
2557
|
`<wf>` and then descends into every live `calls:` child, folding their orders
|