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
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Agent runner and harness policy
|
|
2
|
+
|
|
3
|
+
`owenloop work agent-run` is the only supported dispatcher for workflow Step Agents. The Shift daemon starts `agent-run` children for agent orders. Plugins and skills supervise the Shift daemon; plugins do not package or dispatch a static workflow-worker agent.
|
|
4
|
+
|
|
5
|
+
The runtime worker resolves the verified workflow definition from the local workflow store, selects the final harness after CLI and environment overrides, and runs permission preflight before either a cold start or a resume. A policy refusal starts no model SDK, CLI, or app-server process. The worker prints every refusal reason, releases the held claim, and exits non-zero.
|
|
6
|
+
|
|
7
|
+
Runtime preflight is authoritative. `owenloop work lint` runs the same common and adapter checks for author feedback, but lint cannot account for a later `--harness` or `OWENLOOP_HARNESS` override.
|
|
8
|
+
|
|
9
|
+
Native judge entries do not carry a separately authored `x` map. The definition
|
|
10
|
+
compiler deep-clones the producer step's complete parsed `x` map onto every
|
|
11
|
+
synthesized judge step, and generated and persisted judge orders expose that
|
|
12
|
+
map as `Order.x`. The worker therefore reads the current judge's inherited
|
|
13
|
+
`x.harness` from the same verified definition snapshot used for the judge's
|
|
14
|
+
instructions. Final-adapter selection and mandatory preflight apply before
|
|
15
|
+
both judge cold starts and judge resumes. A judge entry's first-class `model`
|
|
16
|
+
continues to win over an inherited `x.harness.model` value.
|
|
17
|
+
|
|
18
|
+
## `x.harness` permission fields
|
|
19
|
+
|
|
20
|
+
The reserved neutral fields are:
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
x:
|
|
24
|
+
harness:
|
|
25
|
+
id: claude-code
|
|
26
|
+
tools: [Read, Glob]
|
|
27
|
+
disallowedTools: [Bash]
|
|
28
|
+
filesystem: read-only
|
|
29
|
+
network: owenloop-only
|
|
30
|
+
permissionMode: default
|
|
31
|
+
maxTurns: 20
|
|
32
|
+
model: sonnet
|
|
33
|
+
effort: high
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- `tools` and `disallowedTools` accept a comma-separated string or a string array.
|
|
37
|
+
- An absent `tools` field means that the workflow did not declare a built-in-tool allow-list.
|
|
38
|
+
- `tools: []` is an explicit empty allow-list and disables all built-in tools on adapters that support tool lists.
|
|
39
|
+
- `filesystem` is one of `read-only`, `workspace-write`, or `unrestricted`.
|
|
40
|
+
- `network` is one of `owenloop-only` or `unrestricted`.
|
|
41
|
+
- `tools` and `disallowedTools` must not overlap.
|
|
42
|
+
- Invalid types, invalid closed-set values, generated `name`/`description` fields, and the legacy `x.claude-code` carrier are definition errors.
|
|
43
|
+
- Unknown `x.harness` keys remain opaque extension data. The selected adapter may interpret or warn about those keys.
|
|
44
|
+
|
|
45
|
+
A cache created by an older CLI may contain `filesystem` or `network` under `permissions.extensions`. The cache reader and final permission preflight refuse that shape because the old normalization would ignore the restriction. Run `owenloop work prepare <workflow>` again.
|
|
46
|
+
|
|
47
|
+
## Capability matrix
|
|
48
|
+
|
|
49
|
+
| Restriction | Claude Code adapter | Codex adapter |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| absent `tools` | preserves the normal SDK built-in-tool default unless another restriction requires an audited set | supported only because no tool list was authored |
|
|
52
|
+
| `tools: []` | disables all built-in tools; only the born-bound Owenloop control tools remain | refused; Codex cannot enforce per-thread tool lists |
|
|
53
|
+
| non-empty `tools` | enforced through both `tools` and `allowedTools`; settings, skills, and external MCP are isolated so unlisted tools cannot widen the surface | refused |
|
|
54
|
+
| `disallowedTools` | enforced through `disallowedTools` | refused |
|
|
55
|
+
| `filesystem: read-only` | with `network: unrestricted`, uses `Read`, `Glob`, `Grep`, `WebFetch`, and `WebSearch`; with `network: owenloop-only`, uses only `Read`, `Glob`, and `Grep` | refused; Codex cannot prove a complete neutral read-only boundary because app-server configuration layers are outside the thread sandbox |
|
|
56
|
+
| `filesystem: workspace-write` | refused; the adapter cannot enforce an exact workspace boundary | refused; Codex cannot prove a complete neutral workspace-write boundary because app-server configuration layers are outside the thread sandbox |
|
|
57
|
+
| `filesystem: unrestricted` | supported | maps to sandbox `danger-full-access`; open-ended `codexConfig`, external MCP, and operator configuration remain backward compatible because no filesystem boundary is claimed |
|
|
58
|
+
| `network: owenloop-only` | supported through isolated settings, skills, MCP, and built-in tools | refused |
|
|
59
|
+
| `network: unrestricted` | supported | supported with `filesystem: unrestricted`, or with an omitted filesystem field and legacy sandbox `workspace-write` / `danger-full-access`; legacy sandbox `read-only` is refused because Codex has no independent read-only network control |
|
|
60
|
+
| `maxTurns` | enforced by the SDK | refused; Codex app-server has no thread or turn limit parameter |
|
|
61
|
+
|
|
62
|
+
Codex refusal of explicit `filesystem: read-only` and `filesystem: workspace-write` is intentional and runs before both cold start and resume. Codex app-server loads configuration from thread, project, global/managed, and persisted session layers. The pinned Codex version has no reliable switch that isolates every layer, and some layers can introduce host processes, providers, endpoints, MCP servers, or additional writable roots outside the thread sandbox. Partial filtering would claim a boundary the adapter cannot prove, so the adapter starts no app-server process and the worker releases the held claim.
|
|
63
|
+
|
|
64
|
+
Codex also refuses every defined `maxTurns` value before both cold start and resume. Codex app-server has no thread or turn limit parameter, so accepting `maxTurns` would silently discard an authored execution limit. The adapter starts no app-server process and the worker releases the held claim.
|
|
65
|
+
|
|
66
|
+
An omitted `filesystem` field preserves the existing Codex default sandbox behavior. `filesystem: unrestricted` preserves the existing explicit `danger-full-access` behavior. The legacy adapter extension `sandbox` remains available with `read-only`, `workspace-write`, or `danger-full-access` for backward compatibility, but `sandbox` is a vendor-specific pass-through rather than Owenloop's neutral filesystem guarantee. A workflow that requires an enforceable neutral read-only policy must select the Claude Code adapter.
|
|
67
|
+
|
|
68
|
+
The worker-created `owenloop` MCP mount still wins any `mcp_servers.owenloop` name clash. The default unrestricted mount registers `get_order`, `submit`, and `reject`. Codex approval policy still accepts only `untrusted`, `on-request`, or `never`.
|
|
69
|
+
|
|
70
|
+
The Claude Code adapter refuses a `read-only` allow-list containing anything outside `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, and the born-bound control tools. With `network: owenloop-only`, the allowed read-only built-ins narrow to `Read`, `Glob`, and `Grep`; `WebFetch` and `WebSearch` remain available only with `network: unrestricted`. The Claude Code adapter refuses an `owenloop-only` allow-list containing Bash, web tools, skills, agent delegation, or any unaudited tool. The Claude Code adapter also refuses authored external MCP tool names because the current option surface cannot prove an exact per-tool allow-list for an external server.
|
|
71
|
+
|
|
72
|
+
## Owenloop control-plane exception
|
|
73
|
+
|
|
74
|
+
`network: owenloop-only` means that the Step Agent may reach only the born-bound Owenloop MCP control plane for the held order. The exception exists so the Step Agent can call `get_order` and `submit`; without those calls the Step Agent cannot inspect or complete the order.
|
|
75
|
+
|
|
76
|
+
For Claude Code isolation, the adapter sets `settingSources: []`, `strictMcpConfig: true`, disables skills, excludes hooks and external MCP servers, and mounts only the worker-created `owenloop` MCP server. The restricted MCP child positively registers exactly `get_order` and `submit`; the restricted MCP child does not register `reject`. A future work-holder tool therefore does not enter restricted sessions unless the adapter explicitly adds the tool to the positive registration list. The adapter also restricts built-in tools to an audited no-network set. The same option construction runs for cold start and resume.
|
|
77
|
+
|
|
78
|
+
The born-bound Owenloop MCP server is created by the worker from the live workflow, run, origin, account, Shift, and held claim. Workflow extension data cannot replace that mount. During isolation, the adapter adds `mcp__owenloop__get_order` and `mcp__owenloop__submit` to `allowedTools` so both control calls execute without an unattended permission prompt. `allowedTools` controls permission automation; `allowedTools` does not filter the MCP server's `tools/list` response. The positive registration list on the MCP child is the visibility boundary. The adapter also adds `mcp__owenloop__reject` to `disallowedTools` as defense in depth. A direct deny or an MCP wildcard deny that blocks Owenloop `get_order` or `submit` is refused.
|
|
79
|
+
|
|
80
|
+
Outside Claude Code isolation, the default work-holder MCP child continues to register `get_order`, `submit`, and `reject`.
|
|
81
|
+
|
|
82
|
+
## Security boundary
|
|
83
|
+
|
|
84
|
+
`x.harness` permission fields are enforced policy. Adapter preflight must prove that the selected adapter can implement each authored restriction exactly; unsupported policy fails closed.
|
|
85
|
+
|
|
86
|
+
`advisory.tools` is model guidance only. `advisory.tools` does not configure an adapter, does not remove a provider tool, and is not a security boundary.
|
package/docs/authoring.md
CHANGED
|
@@ -78,6 +78,7 @@ steps:
|
|
|
78
78
|
# to the engine, passed through on the order
|
|
79
79
|
# (see below)
|
|
80
80
|
workdir: … # opaque hint passed through on the order; omitted when unset
|
|
81
|
+
workdirFrom: workspace.payload.worktreePath # resolve workdir from a consumed value
|
|
81
82
|
executor: agent # opaque executor value (default: agent); see below
|
|
82
83
|
command: … # required when executor: command; opaque, never shelled out
|
|
83
84
|
spec: # optional opaque config map, shape-checked like x: (a plain map)
|
|
@@ -112,6 +113,37 @@ a literal model id. Pin an exact model when you need reproducibility — just
|
|
|
112
113
|
know the def is now host-specific, on purpose. Omit `model:` entirely and the
|
|
113
114
|
dispatcher uses its default.
|
|
114
115
|
|
|
116
|
+
## `workdirFrom:` — resolve a local workdir from a consumed value
|
|
117
|
+
|
|
118
|
+
`workdirFrom:` sets the existing `Order.workdir` from a nested field in a green,
|
|
119
|
+
plain consumed artifact. The grammar is `<consumedStem>.<dotted.value.path>`:
|
|
120
|
+
|
|
121
|
+
```yaml
|
|
122
|
+
steps:
|
|
123
|
+
- name: provisioner
|
|
124
|
+
consumes: [proposal]
|
|
125
|
+
produces: [workspace]
|
|
126
|
+
- name: builder
|
|
127
|
+
consumes: [workspace]
|
|
128
|
+
produces: [pr]
|
|
129
|
+
workdirFrom: workspace.payload.worktreePath
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The stem named before the dotted value path must also appear in the step's
|
|
133
|
+
`consumes:` list, and the consume must be plain rather than map (`[$i]`) or
|
|
134
|
+
reduce (`[*]`). The engine resolves the longest consumed-stem prefix when an
|
|
135
|
+
artifact stem itself contains dots. `workdir:` and `workdirFrom:` are mutually
|
|
136
|
+
exclusive.
|
|
137
|
+
|
|
138
|
+
At order-build time the engine walks the consumed value using the dotted path.
|
|
139
|
+
A missing field, non-object intermediate, array, non-string final value, empty
|
|
140
|
+
string, or whitespace-only string defers the firing with reason
|
|
141
|
+
`workdir-unresolved`; the engine emits no order and inserts no run. The engine
|
|
142
|
+
passes a valid path through unchanged: the engine does not resolve or normalize
|
|
143
|
+
a relative path and does not change the worker's current-directory semantics.
|
|
144
|
+
The producer and worker must therefore run on the same machine. A permanently
|
|
145
|
+
unresolvable path remains deferred until the producer supplies a valid value.
|
|
146
|
+
|
|
115
147
|
## `executor:` — declaring the executor
|
|
116
148
|
|
|
117
149
|
Every step in every def written before this feature dispatches to an LLM
|
|
@@ -229,6 +261,12 @@ indirection. Two consequences of the local filter are worth stating plainly:
|
|
|
229
261
|
(each folded deferral in a `TickResult` carries its `reason`) so a
|
|
230
262
|
permanently unclaimed step is caught rather than silently stuck.
|
|
231
263
|
|
|
264
|
+
A `workdirFrom` firing can also remain deferred forever with
|
|
265
|
+
`workdir-unresolved`. That reason means the producing step has not supplied a
|
|
266
|
+
usable nested path: the value is missing, has an invalid shape, or is not a
|
|
267
|
+
non-empty string. Fix the producing step or its artifact value; changing the
|
|
268
|
+
consumer's worker does not bypass the engine's workdir resolution check.
|
|
269
|
+
|
|
232
270
|
`capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
|
|
233
271
|
`executor:` says what *kind* of executor should run an order once it's claimed;
|
|
234
272
|
`capabilities:` says *which* caller may claim it in the first place — a tick filter
|
|
@@ -291,6 +329,15 @@ regardless of `executor:` — that requirement is orthogonal to this feature and
|
|
|
291
329
|
applies even to a `executor: command` judge (the field just goes unread by a
|
|
292
330
|
non-agent dispatcher).
|
|
293
331
|
|
|
332
|
+
Author `x:` on the producer step, not on individual judge entries. Every native
|
|
333
|
+
judge synthesized from that producer inherits the producer's complete parsed
|
|
334
|
+
`x:` map. Each judge receives an independent deep clone, so runner-side
|
|
335
|
+
mutation of the producer or one judge cannot alter a sibling judge. When the
|
|
336
|
+
producer omits `x:`, synthesized judges omit `x:` too. In particular, a
|
|
337
|
+
producer's `x.harness` policy governs both the producer order and every native
|
|
338
|
+
judge order. A judge entry's first-class `model:` remains authoritative over an
|
|
339
|
+
inherited `x.harness.model` value.
|
|
340
|
+
|
|
294
341
|
Each judge is a real step under the hood — it fires its own Worker order
|
|
295
342
|
through the normal pipeline, with its own throttles (`cadence:`,
|
|
296
343
|
`maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
|
|
@@ -420,7 +467,7 @@ steps:
|
|
|
420
467
|
produces: [sandbox]
|
|
421
468
|
body: Provision environment.
|
|
422
469
|
- name: deliver
|
|
423
|
-
calls: delivery #
|
|
470
|
+
calls: delivery # bare local name; use <package>/<workflow> for a CAS target
|
|
424
471
|
inputs: # child input → parent artifact (gate: sandbox green)
|
|
425
472
|
proposal: proposal
|
|
426
473
|
produces: [delivered] # one parent artifact; greens when delivery's output greens
|
|
@@ -526,13 +573,17 @@ rather than inlining the payload itself.
|
|
|
526
573
|
|
|
527
574
|
Don't put credentials or secrets in an artifact value. Values are persisted
|
|
528
575
|
as plaintext in the SQLite store (no encryption at rest) and are copied
|
|
529
|
-
verbatim
|
|
530
|
-
|
|
576
|
+
verbatim onto every order that consumes them — anyone who can read the
|
|
577
|
+
database, or a downstream worker's resolved context, can read them.
|
|
531
578
|
|
|
532
579
|
Those values are also *retained*, not just transiently persisted: every
|
|
533
580
|
artifact version is kept (the store never overwrites a prior version in place),
|
|
534
|
-
and every run's issued order packet —
|
|
535
|
-
— is written to the SQLite `run` table
|
|
536
|
-
|
|
581
|
+
and every run's issued order packet — the dynamic input values it consumed
|
|
582
|
+
and its accumulated rejection reasons — is written to the SQLite `run` table
|
|
583
|
+
at claim time and stays there after the run closes and the workflow finishes.
|
|
584
|
+
The step's authored prompt and command text are *not* in that packet: orders
|
|
585
|
+
are reference packets (design doc §29) and carry a `defDigest` pointing at
|
|
586
|
+
the definition snapshot instead, so instruction text is retained once, in the
|
|
587
|
+
definition, not duplicated per firing. A secret that flowed through an input
|
|
537
588
|
therefore lives on in the database until the file itself is disposed of — see
|
|
538
589
|
[Storage](../README.md#storage) for the operator's disposal responsibility.
|
package/docs/bundles.md
ADDED
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
# `.wnlp` bundle format
|
|
2
|
+
|
|
3
|
+
A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces identical archive bytes.
|
|
4
|
+
|
|
5
|
+
The bundle APIs are independent of the local workflow store and the network:
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { digestBundle, inspectBundle, packBundle, unpackBundle } from 'owenloop';
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The command-line equivalents are documented in [`docs/cli.md`](cli.md#bundles).
|
|
12
|
+
|
|
13
|
+
## Source layout
|
|
14
|
+
|
|
15
|
+
A source directory must contain `bundle.yaml` and every path listed by the manifest's `workflows` map. Workflow paths may be at the source root or below a subdirectory. For example:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
report/
|
|
19
|
+
├── bundle.yaml
|
|
20
|
+
├── workflows/
|
|
21
|
+
│ ├── delivery.yaml
|
|
22
|
+
│ ├── init.yaml
|
|
23
|
+
│ └── instructions/
|
|
24
|
+
│ └── writer.md
|
|
25
|
+
└── schemas/
|
|
26
|
+
└── findings.json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The packer recursively includes regular files below the source directory. The packer refuses symlinks, device files, FIFOs, sockets, and any other non-regular filesystem node. Directory entries are implied by file paths and are not stored in the archive.
|
|
30
|
+
|
|
31
|
+
Each workflow definition is authoritative for that workflow's execution. A `bodyFile` reference in a step or judge is relative to the directory containing that workflow YAML file. For example, `bodyFile: instructions/writer.md` in `workflows/delivery.yaml` resolves to `workflows/instructions/writer.md`. The authored `bodyFile` and the resolved archive path must both satisfy the canonical bundle path safety policy. The packer and strict archive reader apply the same rule before parsing the workflow.
|
|
32
|
+
|
|
33
|
+
## `bundle.yaml`
|
|
34
|
+
|
|
35
|
+
The manifest is a package-only document. The manifest does not declare workers, commands, interpreters, scripts, or other execution behavior. Unknown keys, aliases, merge keys, tagged nodes, duplicate keys, non-string mapping keys, and invalid YAML are rejected.
|
|
36
|
+
|
|
37
|
+
The v2 shape is:
|
|
38
|
+
|
|
39
|
+
```yaml
|
|
40
|
+
formatVersion: 2
|
|
41
|
+
package:
|
|
42
|
+
name: owenloop-delivery
|
|
43
|
+
version: 1.0.0
|
|
44
|
+
runtime:
|
|
45
|
+
minVersion: "0.5.1"
|
|
46
|
+
features:
|
|
47
|
+
- harness-policy-enforcement.v1
|
|
48
|
+
- native-judge-policy-inheritance.v1
|
|
49
|
+
workflows:
|
|
50
|
+
delivery: "workflows/delivery.yaml"
|
|
51
|
+
init: "workflows/init.yaml"
|
|
52
|
+
default: "delivery"
|
|
53
|
+
platforms:
|
|
54
|
+
- darwin-arm64
|
|
55
|
+
- linux-amd64
|
|
56
|
+
integrity:
|
|
57
|
+
algorithm: sha256
|
|
58
|
+
files:
|
|
59
|
+
workflows/delivery.yaml: "<64 lowercase hex characters>"
|
|
60
|
+
workflows/init.yaml: "<64 lowercase hex characters>"
|
|
61
|
+
workflows/instructions/writer.md: "<64 lowercase hex characters>"
|
|
62
|
+
schemas/findings.json: "<64 lowercase hex characters>"
|
|
63
|
+
capabilities:
|
|
64
|
+
commands:
|
|
65
|
+
- git
|
|
66
|
+
lock:
|
|
67
|
+
example/research@1.0.0: "<64 lowercase hex characters>"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The following rules apply:
|
|
71
|
+
|
|
72
|
+
- `formatVersion` is exactly `2`. A v1 manifest is not accepted; there is no compatibility parser.
|
|
73
|
+
- `package.name` is a portable package namespace. The default store coordinate for the package is `package.name/package.name@package.version`; an explicit store namespace override may replace the first component. A workflow definition name is not the package name.
|
|
74
|
+
- `package.version` is a non-empty printable ASCII version string without path separators.
|
|
75
|
+
- `runtime` is optional. When present, `runtime` is a closed mapping that contains `minVersion`, `features`, or both; `runtime: {}` is invalid. Runtime requirements are described in [Runtime compatibility](#runtime-compatibility).
|
|
76
|
+
- `workflows` is a non-empty map from workflow names to archive-relative YAML paths. Each workflow name matches `/^[a-z][a-z0-9-]*$/`. Each path must pass the canonical bundle path safety policy, and two workflow names may not point to the same path.
|
|
77
|
+
- A workflow file's `name:` must equal the workflow map key. For example, `workflows.delivery` must point to a file containing `name: delivery`.
|
|
78
|
+
- An installed workflow is addressable from `calls:` by the qualified name `<package>/<workflow>`. A bare `calls: <workflow>` inside a CAS-installed bundle is resolved to a sibling from that same bundle; it does not search unrelated bundles for a same-named workflow. An exact versioned `calls: namespace/name@version` resolves through the verified store-index coordinate to the bundle's selected default workflow, then the engine checks the matching `lock` digest before creating the child.
|
|
79
|
+
- `default` is optional. When present, `default` must be one of the workflow map keys. When absent, a single-workflow package has that one workflow as its implicit default. A package with two or more workflows has no implicit default: the versioned coordinate is not registered as a callable target, while explicit `<package>/<workflow>` targets remain available.
|
|
80
|
+
- `platforms` is a duplicate-free list of portable selector strings. The list is advisory; platform policy is outside the package parser.
|
|
81
|
+
- `integrity.algorithm` is exactly `sha256`.
|
|
82
|
+
- `integrity.files` contains one lowercase 64-hex SHA-256 digest for every regular archive file except `bundle.yaml`. The packer regenerates this map from the source bytes and does not edit the source manifest. Excluding `bundle.yaml` avoids a recursive self-hash; the def digest still covers the complete canonical tar, including `bundle.yaml`.
|
|
83
|
+
- `capabilities` contains requested capability classes and values. The manifest does not grant capabilities.
|
|
84
|
+
- `lock` maps exact versioned `namespace/name@version` call references to lowercase 64-hex **bundle digests**. Every explicit versioned `calls:` target in every workflow must have a matching lock key. A bare same-bundle call has no lock entry: its pin is the containing bundle's own digest. The runtime compares bundle digests at child spawn; it does not compare this lock value with a per-workflow instruction digest.
|
|
85
|
+
|
|
86
|
+
Canonical manifest serialization uses the fixed top-level order `formatVersion`, `package`, optional `runtime`, `workflows`, optional `default`, `platforms`, `integrity`, `capabilities`, `lock`. Runtime fields use the order `minVersion`, then `features`; feature identifiers are sorted by ascending UTF-8 bytes. Other mapping keys and list values use their defined canonical order. Strings use JSON-style double quotes, indentation is two spaces, and the document has exactly one final newline. Inspection rejects a manifest that parses correctly but is not in that canonical byte form.
|
|
87
|
+
|
|
88
|
+
## Runtime compatibility
|
|
89
|
+
|
|
90
|
+
The optional `runtime` mapping declares requirements that the Owenloop process must satisfy before Owenloop returns usable workflow definitions or instructions:
|
|
91
|
+
|
|
92
|
+
```yaml
|
|
93
|
+
runtime:
|
|
94
|
+
minVersion: "0.5.1"
|
|
95
|
+
features:
|
|
96
|
+
- harness-policy-enforcement.v1
|
|
97
|
+
- native-judge-policy-inheritance.v1
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The mapping is strict and closed. Unknown keys are rejected. At least one of `minVersion` and `features` is required.
|
|
101
|
+
|
|
102
|
+
- `minVersion` is exactly one canonical strict SemVer value. Ranges, a leading `v`, surrounding whitespace, and non-canonical forms are invalid. Owenloop compares the running package version with standard SemVer prerelease precedence; build metadata does not affect precedence.
|
|
103
|
+
- `features` is a non-empty, duplicate-free sequence. Each identifier is at most 128 UTF-8 bytes and matches `/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*\.v[1-9][0-9]*$/`: lowercase portable segments ending in a positive, non-zero-padded `.vN` version.
|
|
104
|
+
- When both fields are present, both requirements must pass. The fields use AND semantics, not alternatives.
|
|
105
|
+
|
|
106
|
+
This Owenloop release advertises exactly these feature identifiers:
|
|
107
|
+
|
|
108
|
+
- `harness-policy-enforcement.v1`
|
|
109
|
+
- `native-judge-policy-inheritance.v1`
|
|
110
|
+
|
|
111
|
+
The running version comes from Owenloop's production `packageVersion()` source. A production build that cannot read a valid package version uses the `0.0.0` sentinel. The sentinel fails every declared `minVersion`, including `minVersion: "0.0.0"`, and the refusal tells the operator to install or upgrade Owenloop. The sentinel may still satisfy a feature-only declaration because feature support is evaluated independently.
|
|
112
|
+
|
|
113
|
+
Malformed runtime declarations fail with `BundleError.code === "MANIFEST_ERROR"`. A well-formed declaration that requires a newer Owenloop version or an unsupported feature fails with `BundleError.code === "RUNTIME_INCOMPATIBLE"`. Runtime-incompatible source bundles cannot be packed; runtime-incompatible packed bundles cannot be inspected, unpacked, installed, loaded as instructions, or executed. Definition listing and status discovery retain their existing fail-open behavior: they warn, skip the incompatible installed object, and continue loading unrelated definitions. Instruction and execution resolution fail closed before a command process, agent harness, or provider starts.
|
|
114
|
+
|
|
115
|
+
An absent `runtime` field preserves the previous canonical manifest bytes and bundle digest exactly. Adding, changing, or removing a present runtime declaration changes `bundle.yaml`, the canonical tar bytes, and therefore the content-addressed bundle digest. Readers that predate the runtime contract reject a present `runtime` key as an unknown top-level manifest key; authors must set requirements only when every required consumer supports this contract.
|
|
116
|
+
|
|
117
|
+
## Canonical archive
|
|
118
|
+
|
|
119
|
+
The def digest is the lowercase SHA-256 hash of the exact **uncompressed canonical tar bytes**. The gzip bytes are a transport encoding and are not the bundle identity.
|
|
120
|
+
|
|
121
|
+
For every regular file:
|
|
122
|
+
|
|
123
|
+
- Archive paths use `/` separators and are sorted by ascending UTF-8 bytes. A backslash is rejected as a character in a canonical bundle path; the reader never treats a backslash as an alternate separator.
|
|
124
|
+
- Empty paths, NUL bytes, absolute paths, Windows drive paths, UNC paths, and `.` or `..` path segments are rejected.
|
|
125
|
+
- A regular-file path may not be a complete-segment prefix of another regular-file path. For example, one archive cannot contain both `a` and `a/b` because `a` cannot be both a regular file and a parent directory.
|
|
126
|
+
- The canonical `.wnlp` path policy is deliberately stricter than the GitHub archive compatibility policy used by `owenloop add`. GitHub archive handling keeps its separate compatibility rules; ordinary backslashes that policy accepts are still invalid in canonical bundle paths.
|
|
127
|
+
- `uid` and `gid` are `0`.
|
|
128
|
+
- `uname` and `gname` are empty.
|
|
129
|
+
- `mtime` is `0`.
|
|
130
|
+
- Mode is `0644`, or `0755` when any source execute bit is set. Other mode bits do not affect the output.
|
|
131
|
+
- Short UTF-8 paths use canonical USTAR headers.
|
|
132
|
+
- Paths that do not fit the USTAR name field use one deterministic POSIX PAX `path` record in a `PaxHeader` entry.
|
|
133
|
+
- Header fields use canonical zero-padded octal values, USTAR magic `ustar\0`, version `00`, and zeroed link, device, and prefix fields.
|
|
134
|
+
- Each regular archive file uses typeflag `0`.
|
|
135
|
+
- Every entry's data padding, including the padding after a `PaxHeader` data record, is zero-filled.
|
|
136
|
+
- The archive ends with exactly two zero blocks and no bytes after the terminator.
|
|
137
|
+
|
|
138
|
+
The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Gzip mtime bytes are zero, and gzip header byte 9 (the OS byte) is explicitly forced to zero so Darwin and Linux produce the same bytes.
|
|
139
|
+
|
|
140
|
+
The canonical tar contains regular-file entries only. Parent directories are implied by `/`-separated file paths and are never emitted as tar entries. The strict reader rejects archive symlink, hardlink, device, FIFO, socket, directory, and unknown entry types. The packer rejects source symlinks and non-regular filesystem nodes. Absolute paths, `.` segments, and `..` traversal are refused rather than normalized.
|
|
141
|
+
|
|
142
|
+
The strict reader is as constrained as the writer. Every byte range parsed by the reader is limited to the exact form emitted by the canonical writer, including regular-file data padding and PAX-header data padding, which must be zero. This closes padding malleability: attacker-chosen bytes cannot sit inside the digest-covered tar while remaining absent from every per-file hash.
|
|
143
|
+
|
|
144
|
+
## Reading and extraction safety
|
|
145
|
+
|
|
146
|
+
`inspectBundle` and `unpackBundle` apply bounded compressed size, expanded size, tar-header count, per-file size, and path length limits before returning or writing file data. Strict readers reject malformed checksums and octal fields, truncated headers or data, malformed or dangling PAX metadata, duplicate paths, complete-segment file-prefix collisions, backslashes, unsupported entry types, non-canonical headers, unsorted effective paths, trailing bytes, missing manifests, invalid manifests, runtime-incompatible manifests, missing or invalid workflows, unsafe workflow paths, workflow validation failures, and integrity mismatches.
|
|
147
|
+
|
|
148
|
+
`parseManifestBytes` is the common runtime-admission boundary. Source packing, packed inspection, unpacking, workflow-store installation, installed-object verification, definition discovery, instruction lookup, and worker execution all pass through that boundary before returning usable definitions or instructions.
|
|
149
|
+
|
|
150
|
+
`unpackBundle` validates the complete archive before filesystem writes. The destination must not already exist. The unpacker checks every existing destination ancestor and rejects operator-created symlinks, then writes into a fresh sibling staging directory. The staging directory is renamed into place only after all files are written; failed unpack operations remove staging and leave the destination absent.
|
|
151
|
+
|
|
152
|
+
## Installed-object verification on read
|
|
153
|
+
|
|
154
|
+
The store's bundle ingestor verifies an installed object again every time a resolver needs its contents. The verifier safely enumerates every installed regular file, reads each file once, and preserves the existing detailed refusals for missing integrity-listed files, changed file digests, unlisted extra files, unsafe paths, symlinks, devices, FIFOs, and other wrong filesystem types.
|
|
155
|
+
|
|
156
|
+
After the per-file checks pass, the verifier reconstructs the complete canonical uncompressed tar from the installed files, including `bundle.yaml`. Installed non-executable files reconstruct as canonical mode `0644`; files with any execute bit reconstruct as `0755`. The SHA-256 digest of those canonical tar bytes must equal the object's `objects/sha256/<digest>` content address. This complete-object check covers runtime-only changes and removal of the runtime declaration even though `integrity.files` excludes `bundle.yaml` to avoid a recursive self-hash.
|
|
157
|
+
|
|
158
|
+
A store index entry records the sorted workflow names alongside the package coordinate and bundle digest. Executable definition discovery preserves each verified coordinate and fails closed on corrupt index or object state; read-only status inspection can skip damage only while reporting that its result is incomplete. Runtime instruction resolution reads the verified installed manifest and loads every listed workflow; a requested instruction digest may match any workflow in the installed object. A verification failure prevents the object from populating usable definition and instruction caches. Cache hits are re-verified, and a later failure evicts the cached object.
|
|
159
|
+
|
|
160
|
+
This check is separate from the read-only file modes applied during install. Installation maps canonical `0644` files to read-only `0444` and canonical `0755` files to read/execute-only `0555`, preserving the executable distinction needed to reconstruct identity. Changing an installed object on disk therefore produces an integrity refusal at resolution time, not a best-effort read and not an `unknown-digest` fallback.
|
|
161
|
+
|
|
162
|
+
An executable file installed by an older Owenloop release may already have lost its execute bit because older hardening mapped every regular file to `0444`. Reinstalling the exact original `.wnlp` is a supported atomic repair for that same-digest object. Owenloop first applies strict archive parsing, manifest and runtime admission, configured signature and policy verification, per-file integrity verification, and canonical digest verification to the supplied archive. Owenloop then reconstructs and completely verifies a clean staged object before replacing the broken destination through the normal journaled directory swap. The broken object's bytes are never reused. The prior object remains as the swap backup until the unchanged same-digest index state is durably committed; a failed repair restores the recoverable prior object and index state. A successful repair preserves the existing coordinate-to-digest mapping, and a later reinstall follows normal idempotent deduplication.
|
|
163
|
+
|
|
164
|
+
## Bundle assets during execution
|
|
165
|
+
|
|
166
|
+
When a command or agent step resolves its definition from an installed bundle,
|
|
167
|
+
owenloop sets `OWENLOOP_BUNDLE_DIR` to the verified installed object directory.
|
|
168
|
+
The directory is the bundle root, so a command can reference a shipped script with
|
|
169
|
+
an explicit quoted path:
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
node "$OWENLOOP_BUNDLE_DIR/scripts/provision.mjs"
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
owenloop sets `OWENLOOP_BUNDLE_DIR` only for definitions with installed-bundle
|
|
176
|
+
provenance. A definition without bundle provenance receives no value. Bundle
|
|
177
|
+
scripts must treat an unset or empty variable as a hard error and report a
|
|
178
|
+
message such as `this workflow must run from an installed bundle`; owenloop does
|
|
179
|
+
not synthesize a fallback directory.
|
|
180
|
+
|
|
181
|
+
Command and agent children receive two engine-derived identity variables:
|
|
182
|
+
`OWENLOOP_WORKFLOW` contains the workflow-instance id, and `OWENLOOP_RUN`
|
|
183
|
+
contains the run id. Both variables are always set, including for definitions
|
|
184
|
+
without bundle provenance. A command can read them directly:
|
|
185
|
+
|
|
186
|
+
```sh
|
|
187
|
+
printf '%s %s\n' "$OWENLOOP_WORKFLOW" "$OWENLOOP_RUN"
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
For agent children, admitting a name to `ADMITTED_OWENLOOP_KEYS` is only a
|
|
191
|
+
filter permission: `filterOwenloopEnv` permits an existing value through, but
|
|
192
|
+
does not make that value authoritative. `agent-run` sets both variables from
|
|
193
|
+
the worker's own engine-derived target before starting the child and overwrites
|
|
194
|
+
ambient values, so a nested agent receives its own identity rather than a
|
|
195
|
+
stale parent value.
|
|
196
|
+
|
|
197
|
+
Run identity is safe to expose because the engine derives it from the worker's
|
|
198
|
+
own `--order` argument. Consumed artifact values are attacker-influenceable and
|
|
199
|
+
are not exposed, and command text is not interpolated; no consume-side gate
|
|
200
|
+
exists for either capability.
|
|
201
|
+
|
|
202
|
+
`OWENLOOP_BUNDLE_DIR` is read-only. Workers must never write into the directory.
|
|
203
|
+
The workflow store is content-addressed and verifies the installed object again
|
|
204
|
+
when a resolver reads it. A write changes the object bytes, so the next read
|
|
205
|
+
fails the digest or file-integrity check instead of executing the modified
|
|
206
|
+
bundle. Mount or copy enforcement is not part of the current contract;
|
|
207
|
+
documentation is the enforcement boundary for now.
|
|
208
|
+
|
|
209
|
+
## API results
|
|
210
|
+
|
|
211
|
+
`packBundle(sourceDir)` returns:
|
|
212
|
+
|
|
213
|
+
- `bytes`: the complete gzip-compressed `.wnlp` file;
|
|
214
|
+
- `digest`: the canonical uncompressed-tar digest;
|
|
215
|
+
- `manifest`: the canonical manifest archived in `bytes`; and
|
|
216
|
+
- `entries`: sorted path, size, executable-bit, and per-file digest metadata.
|
|
217
|
+
|
|
218
|
+
`inspectBundle(bytes)` returns the digest, runtime-admitted validated manifest, and entry metadata without writing files. `unpackBundle(bytes, destination)` returns the same inspection result plus the absolute materialized destination path.
|
|
219
|
+
|
|
220
|
+
`digestBundle(bytes)` is the deliberate identity-only exception to runtime admission. The function enforces the compressed and expanded size limits, inflates the gzip payload, and hashes the exact decompressed bytes. The function does not parse or validate a canonical tar and does not parse `bundle.yaml`; therefore `digestBundle` can return a digest for bounded gzip content that is not an admissible bundle, including an archive whose runtime declaration the current Owenloop process cannot satisfy. A successful digest does not mean the content is a canonical tar or that the bundle is admissible for packing, inspection, unpacking, installation, definition loading, instruction lookup, or execution.
|
|
221
|
+
|
|
222
|
+
`owenloop publish` signs exactly `packBundle(sourceDir).digest`: the lowercase 64-hex SHA-256 digest of the uncompressed canonical tar. It does not sign the gzip wrapper bytes or the separate compiled-definition hash used by `push`.
|
|
223
|
+
|
|
224
|
+
All bundle failures are `BundleError` instances with a stable `code` suitable for scripts. The CLI keeps that code in the stderr diagnostic.
|
|
225
|
+
|
|
226
|
+
## Limits
|
|
227
|
+
|
|
228
|
+
The default shared archive limits are:
|
|
229
|
+
|
|
230
|
+
| limit | default |
|
|
231
|
+
|---|---:|
|
|
232
|
+
| compressed input | 256 MiB |
|
|
233
|
+
| expanded tar | 1 GiB |
|
|
234
|
+
| tar headers | 50,000 |
|
|
235
|
+
| one regular file | 100 MiB |
|
|
236
|
+
| one path | 1,024 characters |
|
|
237
|
+
|
|
238
|
+
The in-process APIs accept `limits` overrides through `PackOptions` or `InspectOptions`. Limits apply before archive data is copied or extracted.
|
|
239
|
+
|
|
240
|
+
## Verification example
|
|
241
|
+
|
|
242
|
+
A package can be inspected with both owenloop and a stock tar implementation:
|
|
243
|
+
|
|
244
|
+
```sh
|
|
245
|
+
owenloop bundle inspect ./report-1.2.0.wnlp
|
|
246
|
+
owenloop bundle digest ./report-1.2.0.wnlp
|
|
247
|
+
tar -tzf ./report-1.2.0.wnlp
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
The digest printed by `owenloop bundle digest` is stable across gzip metadata, operating-system, and filesystem timestamp differences when the canonical file bytes and executable-bit choices are unchanged. CI recomputes a checked-in golden vector on both Ubuntu and macOS to guard this cross-platform stability.
|