owenloop 0.4.1 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +71 -0
- package/README.md +182 -53
- package/bin/owenloop.mjs +50 -2
- package/dist/packages/work/src/agent/brief.d.ts +176 -0
- package/dist/packages/work/src/agent/brief.js +197 -0
- package/dist/packages/work/src/agent/loop.d.ts +141 -0
- package/dist/packages/work/src/agent/loop.js +669 -0
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +92 -0
- package/dist/packages/work/src/bundle/cache.js +338 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
- package/dist/packages/work/src/bundle/fetch.js +345 -0
- package/dist/packages/work/src/bundle/types.d.ts +164 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
- package/dist/packages/work/src/consumed-verifier.js +205 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/instructions.d.ts +99 -0
- package/dist/packages/work/src/exec/instructions.js +323 -0
- package/dist/packages/work/src/exec/loop.d.ts +40 -0
- package/dist/packages/work/src/exec/loop.js +332 -0
- package/dist/packages/work/src/exec/payload.d.ts +29 -0
- package/dist/packages/work/src/exec/payload.js +54 -0
- package/dist/packages/work/src/exec/receipt.d.ts +41 -0
- package/dist/packages/work/src/exec/receipt.js +32 -0
- package/dist/packages/work/src/exec/runner.d.ts +71 -0
- package/dist/packages/work/src/exec/runner.js +256 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +134 -0
- package/dist/packages/work/src/harness/claude.d.ts +140 -0
- package/dist/packages/work/src/harness/claude.js +837 -0
- package/dist/packages/work/src/harness/codex.d.ts +111 -0
- package/dist/packages/work/src/harness/codex.js +1024 -0
- package/dist/packages/work/src/harness/contract.d.ts +308 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +91 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
- package/dist/packages/work/src/harness/permissions.d.ts +75 -0
- package/dist/packages/work/src/harness/permissions.js +182 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +181 -0
- package/dist/packages/work/src/harness/session-store.js +523 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +75 -0
- package/dist/packages/work/src/hold/mcp.js +264 -0
- package/dist/packages/work/src/hub/client.d.ts +23 -0
- package/dist/packages/work/src/hub/client.js +91 -0
- package/dist/packages/work/src/hub/types.d.ts +326 -0
- package/dist/packages/work/src/hub/types.js +26 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
- package/dist/packages/work/src/owenloop-bin.js +18 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
- package/dist/packages/work/src/roles/agent-run.js +529 -0
- package/dist/packages/work/src/roles/exec.d.ts +48 -0
- package/dist/packages/work/src/roles/exec.js +228 -0
- package/dist/packages/work/src/roles/hold.d.ts +72 -0
- package/dist/packages/work/src/roles/hold.js +363 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +58 -0
- package/dist/packages/work/src/roles/lint.js +234 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +71 -0
- package/dist/packages/work/src/roles/shift.d.ts +13 -0
- package/dist/packages/work/src/roles/shift.js +250 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +136 -0
- package/dist/packages/work/src/settings/settings.js +155 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +131 -0
- package/dist/packages/work/src/shift/loop.js +751 -0
- package/dist/packages/work/src/shift/protocol.d.ts +95 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +45 -0
- package/dist/packages/work/src/shift/runtime.js +337 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +109 -0
- package/dist/packages/work/src/shift/spawn.js +158 -0
- package/dist/packages/work/src/shift/state.d.ts +79 -0
- package/dist/packages/work/src/shift/state.js +385 -0
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/src/add.d.ts +189 -0
- package/dist/src/add.js +300 -0
- package/dist/src/archive.d.ts +97 -0
- package/dist/src/archive.js +591 -0
- package/dist/src/bundle/index.d.ts +64 -0
- package/dist/src/bundle/index.js +508 -0
- package/dist/src/bundle/manifest.d.ts +50 -0
- package/dist/src/bundle/manifest.js +435 -0
- package/dist/src/bundle/runtime.d.ts +26 -0
- package/dist/src/bundle/runtime.js +64 -0
- package/dist/src/bundle/tar.d.ts +62 -0
- package/dist/src/bundle/tar.js +238 -0
- package/dist/src/bundle/types.d.ts +105 -0
- package/dist/src/bundle/types.js +21 -0
- package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
- package/dist/src/cli.js +5968 -0
- package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
- package/dist/{credentials.js → src/credentials.js} +35 -31
- package/dist/src/crypto/allowed-signers.d.ts +68 -0
- package/dist/src/crypto/allowed-signers.js +307 -0
- package/dist/src/crypto/canonical.d.ts +8 -0
- package/dist/src/crypto/canonical.js +92 -0
- package/dist/src/crypto/chain.d.ts +65 -0
- package/dist/src/crypto/chain.js +377 -0
- package/dist/src/crypto/dsse.d.ts +209 -0
- package/dist/src/crypto/dsse.js +282 -0
- package/dist/src/crypto/enrollment.d.ts +78 -0
- package/dist/src/crypto/enrollment.js +186 -0
- package/dist/src/crypto/index.d.ts +48 -0
- package/dist/src/crypto/index.js +44 -0
- package/dist/src/crypto/keys.d.ts +258 -0
- package/dist/src/crypto/keys.js +908 -0
- package/dist/src/crypto/org-root.d.ts +33 -0
- package/dist/src/crypto/org-root.js +78 -0
- package/dist/src/crypto/origin-rules.d.ts +56 -0
- package/dist/src/crypto/origin-rules.js +143 -0
- package/dist/src/crypto/policy-floor.d.ts +98 -0
- package/dist/src/crypto/policy-floor.js +353 -0
- package/dist/src/crypto/records.d.ts +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
- package/dist/{defs.js → src/defs.js} +181 -61
- package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
- package/dist/{engine.js → src/engine.js} +251 -47
- package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
- package/dist/{factory.js → src/factory.js} +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
- package/dist/{hub.js → src/hub.js} +493 -52
- package/dist/src/index.d.ts +47 -0
- package/dist/src/index.js +41 -0
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +38 -0
- package/dist/src/lock.js +325 -0
- package/dist/src/mcp/serve.d.ts +109 -0
- package/dist/{mcp → src/mcp}/serve.js +335 -75
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +18 -10
- package/dist/{model.d.ts → src/model.d.ts} +15 -0
- package/dist/{model.js → src/model.js} +112 -2
- package/dist/src/order-resolver.d.ts +184 -0
- package/dist/src/order-resolver.js +252 -0
- package/dist/src/package-version.d.ts +10 -0
- package/dist/src/package-version.js +42 -0
- package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
- package/dist/{paths.js → src/paths.js} +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/{types.d.ts → src/types.d.ts} +58 -24
- package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
- package/dist/src/untar.js +38 -0
- package/dist/{util.d.ts → src/util.d.ts} +3 -2
- package/dist/{util.js → src/util.js} +3 -2
- package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
- package/dist/{owenwork.js → src/work-settings.js} +27 -27
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +150 -59
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1758 -163
- package/docs/crypto.md +816 -0
- package/docs/design.md +374 -52
- package/docs/embedding.md +135 -27
- package/docs/wire-contracts.md +380 -0
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +22 -8
- package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
- package/plugins/claude-code/plugin/.mcp.json +14 -0
- package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
- package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
- package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
- package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
- package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
- package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
- package/plugins/codex/.agents/plugins/marketplace.json +21 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
- package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
- package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
- package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
- package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
- package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
- package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
- package/dist/add.d.ts +0 -384
- package/dist/add.js +0 -834
- package/dist/cli.js +0 -3270
- package/dist/index.d.ts +0 -32
- package/dist/index.js +0 -23
- package/dist/lock.d.ts +0 -80
- package/dist/lock.js +0 -217
- package/dist/mcp/serve.d.ts +0 -84
- package/dist/untar.js +0 -164
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
|
@@ -1,35 +1,35 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* execution settings file writer — the ONE place the root `owenloop` CLI writes
|
|
3
|
+
* into the execution-side settings file.
|
|
4
4
|
*
|
|
5
|
-
* `
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
5
|
+
* `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
|
|
6
|
+
* settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
|
|
7
|
+
* NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
|
|
8
|
+
* `owenloop setup` can point `owenloop work` at the hub it just authenticated
|
|
9
|
+
* against.
|
|
10
10
|
*
|
|
11
11
|
* This module writes exactly ONE key — `hubOrigin` — and preserves every other
|
|
12
|
-
* key byte-for-byte (forward-compat with
|
|
13
|
-
* `stateDir`, `dispatchCap`, `commandRouting`, and any future
|
|
14
|
-
* never writes a secret: nothing secret is in scope here by
|
|
15
|
-
* hub ORIGIN is public).
|
|
12
|
+
* key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
|
|
13
|
+
* `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
|
|
14
|
+
* unknown key). It never writes a secret: nothing secret is in scope here by
|
|
15
|
+
* construction (the hub ORIGIN is public).
|
|
16
16
|
*
|
|
17
17
|
* Corrupt-file policy: a settings file that exists but does not parse as a JSON
|
|
18
18
|
* OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
|
|
19
|
-
* it cannot safely merge into. That mirrors
|
|
20
|
-
* family ("not an object").
|
|
19
|
+
* it cannot safely merge into. That mirrors the work settings validator's
|
|
20
|
+
* wording family ("not an object").
|
|
21
21
|
*
|
|
22
22
|
* Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
|
|
23
23
|
* util.ts — no CLI/engine closure.
|
|
24
24
|
*/
|
|
25
25
|
/**
|
|
26
|
-
* The
|
|
27
|
-
* set and non-blank) wins over `HOME`, matching
|
|
26
|
+
* The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
|
|
27
|
+
* set and non-blank) wins over `HOME`, matching owenloop's own resolution and
|
|
28
28
|
* the owenloop credential store's `configDir`. Throws when neither is set.
|
|
29
29
|
*/
|
|
30
|
-
export declare function
|
|
30
|
+
export declare function owenloopSettingsPath(env: Record<string, string | undefined>): string;
|
|
31
31
|
/**
|
|
32
|
-
* Read and parse the
|
|
32
|
+
* Read and parse the execution settings file at `path`.
|
|
33
33
|
*
|
|
34
34
|
* - Missing file → `null` (an absent settings file is not an error; the writer
|
|
35
35
|
* creates one).
|
|
@@ -38,20 +38,20 @@ export declare function owenworkSettingsPath(env: Record<string, string | undefi
|
|
|
38
38
|
* `null`, a number, a string) → a hard `CliError` naming the path. The writer
|
|
39
39
|
* must never clobber a file it cannot merge into.
|
|
40
40
|
*/
|
|
41
|
-
export declare function
|
|
42
|
-
/** The outcome of a `
|
|
41
|
+
export declare function readOwenloopSettingsRaw(path: string): Record<string, unknown> | null;
|
|
42
|
+
/** The outcome of a `writeOwenloopHubOrigin` call — the path written and the
|
|
43
43
|
* previous `hubOrigin` value (`undefined` when the key was absent or the file
|
|
44
44
|
* did not exist), so a caller can report an old→new transition. */
|
|
45
|
-
export interface
|
|
45
|
+
export interface OwenloopWriteResult {
|
|
46
46
|
path: string;
|
|
47
47
|
previous: string | undefined;
|
|
48
48
|
}
|
|
49
49
|
/**
|
|
50
|
-
* Set ONLY the `hubOrigin` key in the
|
|
50
|
+
* Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
|
|
51
51
|
* preserving every other key. Read the existing file (a parse failure is a hard
|
|
52
52
|
* `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
|
|
53
53
|
* directory, and write atomically (temp + rename via `writeFileAtomic`). The
|
|
54
54
|
* file is pretty-printed with a trailing newline. Returns the path and the
|
|
55
55
|
* previous `hubOrigin` (if any).
|
|
56
56
|
*/
|
|
57
|
-
export declare function
|
|
57
|
+
export declare function writeOwenloopHubOrigin(env: Record<string, string | undefined>, origin: string): OwenloopWriteResult;
|
|
@@ -1,23 +1,23 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* execution settings file writer — the ONE place the root `owenloop` CLI writes
|
|
3
|
+
* into the execution-side settings file.
|
|
4
4
|
*
|
|
5
|
-
* `
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
5
|
+
* `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
|
|
6
|
+
* settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
|
|
7
|
+
* NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
|
|
8
|
+
* `owenloop setup` can point `owenloop work` at the hub it just authenticated
|
|
9
|
+
* against.
|
|
10
10
|
*
|
|
11
11
|
* This module writes exactly ONE key — `hubOrigin` — and preserves every other
|
|
12
|
-
* key byte-for-byte (forward-compat with
|
|
13
|
-
* `stateDir`, `dispatchCap`, `commandRouting`, and any future
|
|
14
|
-
* never writes a secret: nothing secret is in scope here by
|
|
15
|
-
* hub ORIGIN is public).
|
|
12
|
+
* key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
|
|
13
|
+
* `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
|
|
14
|
+
* unknown key). It never writes a secret: nothing secret is in scope here by
|
|
15
|
+
* construction (the hub ORIGIN is public).
|
|
16
16
|
*
|
|
17
17
|
* Corrupt-file policy: a settings file that exists but does not parse as a JSON
|
|
18
18
|
* OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
|
|
19
|
-
* it cannot safely merge into. That mirrors
|
|
20
|
-
* family ("not an object").
|
|
19
|
+
* it cannot safely merge into. That mirrors the work settings validator's
|
|
20
|
+
* wording family ("not an object").
|
|
21
21
|
*
|
|
22
22
|
* Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
|
|
23
23
|
* util.ts — no CLI/engine closure.
|
|
@@ -27,21 +27,21 @@ import { dirname, join } from 'node:path';
|
|
|
27
27
|
import { writeFileAtomic } from "./hub.js";
|
|
28
28
|
import { CliError } from "./util.js";
|
|
29
29
|
/**
|
|
30
|
-
* The
|
|
31
|
-
* set and non-blank) wins over `HOME`, matching
|
|
30
|
+
* The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
|
|
31
|
+
* set and non-blank) wins over `HOME`, matching owenloop's own resolution and
|
|
32
32
|
* the owenloop credential store's `configDir`. Throws when neither is set.
|
|
33
33
|
*/
|
|
34
|
-
export function
|
|
34
|
+
export function owenloopSettingsPath(env) {
|
|
35
35
|
const xdg = env.XDG_CONFIG_HOME;
|
|
36
36
|
if (xdg && xdg.trim() !== '')
|
|
37
|
-
return join(xdg, '
|
|
37
|
+
return join(xdg, 'owenloop', 'settings.json');
|
|
38
38
|
const home = env.HOME;
|
|
39
39
|
if (home && home.trim() !== '')
|
|
40
|
-
return join(home, '.config', '
|
|
41
|
-
throw new CliError('cannot locate a config directory for
|
|
40
|
+
return join(home, '.config', 'owenloop', 'settings.json');
|
|
41
|
+
throw new CliError('cannot locate a config directory for execution settings: set HOME or XDG_CONFIG_HOME');
|
|
42
42
|
}
|
|
43
43
|
/**
|
|
44
|
-
* Read and parse the
|
|
44
|
+
* Read and parse the execution settings file at `path`.
|
|
45
45
|
*
|
|
46
46
|
* - Missing file → `null` (an absent settings file is not an error; the writer
|
|
47
47
|
* creates one).
|
|
@@ -50,7 +50,7 @@ export function owenworkSettingsPath(env) {
|
|
|
50
50
|
* `null`, a number, a string) → a hard `CliError` naming the path. The writer
|
|
51
51
|
* must never clobber a file it cannot merge into.
|
|
52
52
|
*/
|
|
53
|
-
export function
|
|
53
|
+
export function readOwenloopSettingsRaw(path) {
|
|
54
54
|
if (!existsSync(path))
|
|
55
55
|
return null;
|
|
56
56
|
let parsed;
|
|
@@ -58,24 +58,24 @@ export function readOwenworkSettingsRaw(path) {
|
|
|
58
58
|
parsed = JSON.parse(readFileSync(path, 'utf8'));
|
|
59
59
|
}
|
|
60
60
|
catch {
|
|
61
|
-
throw new CliError(`
|
|
61
|
+
throw new CliError(`execution settings file at ${path} is not valid JSON — fix or remove it before running setup`);
|
|
62
62
|
}
|
|
63
63
|
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
64
|
-
throw new CliError(`
|
|
64
|
+
throw new CliError(`execution settings file at ${path} is not a JSON object — fix or remove it before running setup`);
|
|
65
65
|
}
|
|
66
66
|
return parsed;
|
|
67
67
|
}
|
|
68
68
|
/**
|
|
69
|
-
* Set ONLY the `hubOrigin` key in the
|
|
69
|
+
* Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
|
|
70
70
|
* preserving every other key. Read the existing file (a parse failure is a hard
|
|
71
71
|
* `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
|
|
72
72
|
* directory, and write atomically (temp + rename via `writeFileAtomic`). The
|
|
73
73
|
* file is pretty-printed with a trailing newline. Returns the path and the
|
|
74
74
|
* previous `hubOrigin` (if any).
|
|
75
75
|
*/
|
|
76
|
-
export function
|
|
77
|
-
const path =
|
|
78
|
-
const existing =
|
|
76
|
+
export function writeOwenloopHubOrigin(env, origin) {
|
|
77
|
+
const path = owenloopSettingsPath(env);
|
|
78
|
+
const existing = readOwenloopSettingsRaw(path);
|
|
79
79
|
const previous = existing !== undefined && existing !== null && typeof existing.hubOrigin === 'string' ? existing.hubOrigin : undefined;
|
|
80
80
|
const merged = { ...(existing ?? {}), hubOrigin: origin };
|
|
81
81
|
mkdirSync(dirname(path), { recursive: true });
|
|
@@ -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,12 +78,13 @@ 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
|
-
|
|
82
|
-
|
|
81
|
+
workdirFrom: workspace.payload.worktreePath # resolve workdir from a consumed value
|
|
82
|
+
executor: agent # opaque executor value (default: agent); see below
|
|
83
|
+
command: … # required when executor: command; opaque, never shelled out
|
|
83
84
|
spec: # optional opaque config map, shape-checked like x: (a plain map)
|
|
84
85
|
anything: goes # contents never read by the engine; see below
|
|
85
|
-
|
|
86
|
-
# claim filtering (tick --
|
|
86
|
+
capabilities: [nightly, batch] # optional routing capabilities for peer-orchestrator
|
|
87
|
+
# claim filtering (tick --capability); empty = absent; see below
|
|
87
88
|
x: # optional; opaque extension map, passed through
|
|
88
89
|
anything: goes # untouched onto the order (Order.x); see design.md §27.3
|
|
89
90
|
```
|
|
@@ -91,7 +92,7 @@ steps:
|
|
|
91
92
|
## `model:` — quality tiers, not vendor ids
|
|
92
93
|
|
|
93
94
|
The engine never calls a model; `model:` is an opaque string that rides the
|
|
94
|
-
order to whatever dispatches your
|
|
95
|
+
order to whatever dispatches your Step Agents (an agent skill, a runner, your own
|
|
95
96
|
loop). Portable workflows should declare **intent** with one of four tier
|
|
96
97
|
names and let the dispatcher bind them to the host it runs on — Claude Code,
|
|
97
98
|
Codex, Gemini CLI, whatever:
|
|
@@ -112,87 +113,164 @@ 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
|
|
|
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
|
+
|
|
147
|
+
## `executor:` — declaring the executor
|
|
116
148
|
|
|
117
149
|
Every step in every def written before this feature dispatches to an LLM
|
|
118
|
-
agent — that's still the default, and omitting `
|
|
119
|
-
def byte-for-byte unchanged. `
|
|
150
|
+
agent — that's still the default, and omitting `executor:` entirely leaves a
|
|
151
|
+
def byte-for-byte unchanged. `executor:` lets a step opt into a *different*
|
|
120
152
|
kind of executor instead: a shell command, a webhook, a browser-automation
|
|
121
153
|
runner, anything a dispatcher on the other end of `tick` knows how to run.
|
|
122
|
-
The engine never executes anything itself — `
|
|
154
|
+
The engine never executes anything itself — `executor:` is an opaque field
|
|
123
155
|
that rides the order (same pass-through contract as `model`) for whatever
|
|
124
|
-
drives your
|
|
156
|
+
drives your Step Agents to switch on.
|
|
125
157
|
|
|
126
158
|
```yaml
|
|
127
159
|
steps:
|
|
128
160
|
- name: tester
|
|
129
161
|
consumes: [reviewed_plan]
|
|
130
162
|
produces: [result]
|
|
131
|
-
|
|
132
|
-
command: npm test # required when
|
|
163
|
+
executor: command # opaque to the engine; default is 'agent'
|
|
164
|
+
command: npm test # required when executor: command; never parsed or shelled out
|
|
133
165
|
spec: # optional opaque config for the dispatcher
|
|
134
166
|
timeout: 300
|
|
135
167
|
workdir: .
|
|
136
|
-
body: "" # not required for
|
|
168
|
+
body: "" # not required for executor: command
|
|
137
169
|
```
|
|
138
170
|
|
|
139
171
|
Two shape rules, both enforced at load time, everything else opaque:
|
|
140
172
|
|
|
141
|
-
- **`
|
|
173
|
+
- **`executor: command` requires `command:`.** A `command`-executor step with no
|
|
142
174
|
`command:` is a load-time `DefError` — the dispatcher would have nothing to
|
|
143
175
|
run.
|
|
144
|
-
- **`
|
|
176
|
+
- **`executor: agent` (explicit) requires a real `body:`.** Omitting `executor:`
|
|
145
177
|
still defaults to `'agent'` and still needs no body-shape check beyond
|
|
146
178
|
today's behavior — this rule only fires when a step *explicitly* writes
|
|
147
|
-
`
|
|
179
|
+
`executor: agent` and leaves `body:` empty, which is almost certainly a
|
|
148
180
|
mistake (an agent step with no prompt).
|
|
149
181
|
|
|
150
|
-
Any other `
|
|
182
|
+
Any other `executor` value (`browser-automation`, `webhook`, your own executor value) is
|
|
151
183
|
fully opaque — no `body:`/`command:` requirement at all. A definition can
|
|
152
|
-
optionally declare `
|
|
184
|
+
optionally declare `executors: [agent, command]` at the top level as a typo
|
|
153
185
|
guard; when present, `validateDef` rejects any step (or judge — see below)
|
|
154
|
-
whose effective
|
|
186
|
+
whose effective executor (after the `agent` default) isn't in the list:
|
|
155
187
|
|
|
156
188
|
```yaml
|
|
157
189
|
name: my-workflow
|
|
158
|
-
|
|
190
|
+
executors: [agent, command] # optional allow-list; absent = any executor string accepted
|
|
159
191
|
```
|
|
160
192
|
|
|
161
193
|
`command:` and `spec:` are opaque the same way `x:` is: `command` is
|
|
162
194
|
shape-checked as a string, `spec` as a plain map, and neither is ever read or
|
|
163
|
-
interpreted by the engine beyond that. All three (`
|
|
195
|
+
interpreted by the engine beyond that. All three (`executor`, `command`,
|
|
164
196
|
`spec`) ride through `buildOrder` onto the emitted `Order` untouched, exactly
|
|
165
197
|
like `model` and `workdir`. See [`docs/design.md` §27.4](design.md) for the
|
|
166
198
|
full contract.
|
|
167
199
|
|
|
168
|
-
## `
|
|
169
|
-
|
|
170
|
-
`
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
200
|
+
## `capabilities:` — logical capability tags
|
|
201
|
+
|
|
202
|
+
`capabilities:` is an optional list of strings on a step naming what that step
|
|
203
|
+
*needs* — `gpu`, `repo-access` — not where it runs. They are part of **your**
|
|
204
|
+
vocabulary as a def author: a capability tag, chosen to describe the work.
|
|
205
|
+
An empty `capabilities:` list normalizes to absent.
|
|
206
|
+
|
|
207
|
+
**Never write a crew name in a def.** A crew is a deployment fact belonging to
|
|
208
|
+
one org on one hub; a def is portable. The indirection below is what keeps the
|
|
209
|
+
two apart.
|
|
210
|
+
|
|
211
|
+
**Golden path: most defs need no capabilities at all.** A step **without capabilities** routes
|
|
212
|
+
to the run's `defaultCrew` param if one was given, else to the starter's
|
|
213
|
+
personal crew. That is the default path, and it is the right one until you have
|
|
214
|
+
a fleet with genuinely different machines in it. Capabilities and routes are the
|
|
215
|
+
"advanced: teams & fleets" path — reach for a capability only when a step needs a
|
|
216
|
+
*specific* kind of machine.
|
|
217
|
+
|
|
218
|
+
### On a hub: an admin binds each capability to a crew
|
|
219
|
+
|
|
220
|
+
On a hub, every capability a step uses must be **bound to at least one crew by an org
|
|
221
|
+
admin** — `owenloop capability bind <capability> <crew>`, or Console → Settings → Capabilities.
|
|
222
|
+
A capability may bind several crews, and each `capability bind` ADDS one. See
|
|
223
|
+
[capability routes](cli.md#capability-routes) for the commands.
|
|
224
|
+
|
|
225
|
+
- **An unbound capability fails the run at `start_run`**, with an error naming the
|
|
226
|
+
capability and carrying the exact fix command. That fail-fast is deliberate: the
|
|
227
|
+
old behavior was an order that sat unserved forever. Route is **explicit
|
|
228
|
+
only** — there is no implicit fallback in which an unbound capability routes
|
|
229
|
+
somewhere by itself.
|
|
230
|
+
- **Routes are live, and that is the headline.** Adding a crew to a capability
|
|
231
|
+
widens who serves it at the next poll of every in-flight run; removing the
|
|
232
|
+
capability's **last live** route pauses the steps that use it until it is bound
|
|
233
|
+
again. As an author this means your def does **not** need re-publishing when
|
|
234
|
+
the fleet moves: the operator ADDS the new crew — from that moment both crews
|
|
235
|
+
serve the capability — and then REMOVES the old one, and your running work follows
|
|
236
|
+
across without a restart.
|
|
237
|
+
|
|
238
|
+
### Locally: capabilities are a tick filter
|
|
239
|
+
|
|
240
|
+
The local/OSS engine has no capability route table; there, the same capabilities act as a
|
|
241
|
+
work-splitting filter so several orchestrators ticking the *same* database can
|
|
242
|
+
divide the work. A tick caller may pass one or more `--capability <x>` filters (CLI)
|
|
243
|
+
or `engine.tick(wf, { capabilities: [...] })` (embedding), and a step is left for a
|
|
174
244
|
*different* caller only when **both** the caller's filter and the step's own
|
|
175
|
-
`
|
|
176
|
-
reason `
|
|
177
|
-
no filter at all) ticks it.
|
|
245
|
+
`capabilities:` are non-empty and share no value — that step's firings defer with
|
|
246
|
+
reason `capability-mismatch` until a caller whose filter matches (or a caller with
|
|
247
|
+
no filter at all) ticks it.
|
|
178
248
|
|
|
179
|
-
|
|
249
|
+
Capabilities are logical tags in both worlds; only the hub adds the route
|
|
250
|
+
indirection. Two consequences of the local filter are worth stating plainly:
|
|
180
251
|
|
|
181
252
|
- **Routing, not authorization.** A caller that passes *no* filter claims every
|
|
182
|
-
step,
|
|
183
|
-
without a filter.
|
|
184
|
-
boundary; never rely on them to keep a step away from a
|
|
253
|
+
step, with capabilities or not — and any Step Agent that can reach the database can tick
|
|
254
|
+
without a filter. Locally, capabilities are a work-splitting convenience, never a security
|
|
255
|
+
boundary; never rely on them to keep a step away from a Step Agent that shouldn't
|
|
185
256
|
run it.
|
|
186
|
-
- **Starvation hazard.** If every live caller ticks with a
|
|
187
|
-
none of them intersects a given step's
|
|
188
|
-
deferred forever with `
|
|
189
|
-
Operators running
|
|
257
|
+
- **Starvation hazard.** If every live caller ticks with a capability filter and
|
|
258
|
+
none of them intersects a given step's capabilities, that step's orders sit
|
|
259
|
+
deferred forever with `capability-mismatch` — no caller ever claims them.
|
|
260
|
+
Operators running capability-filtered callers should monitor the deferred/blocked entries
|
|
190
261
|
(each folded deferral in a `TickResult` carries its `reason`) so a
|
|
191
262
|
permanently unclaimed step is caught rather than silently stuck.
|
|
192
263
|
|
|
193
|
-
`
|
|
194
|
-
`
|
|
195
|
-
|
|
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
|
+
|
|
270
|
+
`capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
|
|
271
|
+
`executor:` says what *kind* of executor should run an order once it's claimed;
|
|
272
|
+
`capabilities:` says *which* caller may claim it in the first place — a tick filter
|
|
273
|
+
locally, a bound crew on a hub.
|
|
196
274
|
|
|
197
275
|
## `produces:` vs `generates:`
|
|
198
276
|
|
|
@@ -235,23 +313,32 @@ steps:
|
|
|
235
313
|
# reads the producer's inputs (question)
|
|
236
314
|
- name: ci-gate
|
|
237
315
|
body: "unused by a command judge, but still a required field" # every
|
|
238
|
-
# judge needs body/bodyFile regardless of
|
|
239
|
-
|
|
240
|
-
command: scripts/ci-gate.sh #
|
|
316
|
+
# judge needs body/bodyFile regardless of executor
|
|
317
|
+
executor: command # judges can be deterministic too — same
|
|
318
|
+
command: scripts/ci-gate.sh # executor:/command: contract as a normal step
|
|
241
319
|
maxAttempts: 5 # producer's cap (default for every produce on this step)
|
|
242
320
|
# — also bounds judge-reject → rebuild loops; `report`
|
|
243
321
|
# above could set its own maxAttempts: to override it
|
|
244
322
|
```
|
|
245
323
|
|
|
246
|
-
A judge entry accepts the same `
|
|
247
|
-
normal step (see [`
|
|
324
|
+
A judge entry accepts the same `executor:`/`command:`/`spec:` fields as a
|
|
325
|
+
normal step (see [`executor:` above](#executor--declaring-the-executor)) — a
|
|
248
326
|
judge can be a deterministic check (a script's exit status) instead of an
|
|
249
327
|
LLM verdict. Note `body:`/`bodyFile:` is still required on every judge
|
|
250
|
-
regardless of `
|
|
251
|
-
applies even to a `
|
|
328
|
+
regardless of `executor:` — that requirement is orthogonal to this feature and
|
|
329
|
+
applies even to a `executor: command` judge (the field just goes unread by a
|
|
252
330
|
non-agent dispatcher).
|
|
253
331
|
|
|
254
|
-
|
|
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
|
+
|
|
341
|
+
Each judge is a real step under the hood — it fires its own Worker order
|
|
255
342
|
through the normal pipeline, with its own throttles (`cadence:`,
|
|
256
343
|
`maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
|
|
257
344
|
`report`, it lands `submitted` (not `green`) instead — schema-valid, but
|
|
@@ -365,7 +452,7 @@ for brand-new combined workflows where nothing downstream expects the original s
|
|
|
365
452
|
names.
|
|
366
453
|
|
|
367
454
|
**`calls:` (Mode 2, runtime)** delegates to a **separate child instance** at runtime
|
|
368
|
-
instead of inlining. The `calls:` step is machine-handled — it never emits a
|
|
455
|
+
instead of inlining. The `calls:` step is machine-handled — it never emits a Worker
|
|
369
456
|
job. Use it to embed an existing workflow as a black box, keeping its internals hidden.
|
|
370
457
|
|
|
371
458
|
```yaml
|
|
@@ -380,7 +467,7 @@ steps:
|
|
|
380
467
|
produces: [sandbox]
|
|
381
468
|
body: Provision environment.
|
|
382
469
|
- name: deliver
|
|
383
|
-
calls: delivery #
|
|
470
|
+
calls: delivery # bare local name; use <package>/<workflow> for a CAS target
|
|
384
471
|
inputs: # child input → parent artifact (gate: sandbox green)
|
|
385
472
|
proposal: proposal
|
|
386
473
|
produces: [delivered] # one parent artifact; greens when delivery's output greens
|
|
@@ -392,7 +479,7 @@ steps:
|
|
|
392
479
|
```
|
|
393
480
|
|
|
394
481
|
The engine spawns the child when the gate inputs are green, greens the parent's
|
|
395
|
-
`calls:` output when the child's declared output greens (no
|
|
482
|
+
`calls:` output when the child's declared output greens (no Worker run), and re-provides
|
|
396
483
|
inputs to the existing child if a gate input changes — it never spawns a duplicate.
|
|
397
484
|
|
|
398
485
|
| | `include:` (Mode 1) | `calls:` (Mode 2) |
|
|
@@ -429,7 +516,7 @@ By default a step fires when its consumed inputs are all green (`inputsGreen`).
|
|
|
429
516
|
evaluator*: a final step that inspects the finished workflow and greens an `outcome`.
|
|
430
517
|
- **`idle`** — fire when the workflow has made no progress for longer than `idleAfter`
|
|
431
518
|
(required). Use for a watchdog, a stuck-detector, or a timeout handler.
|
|
432
|
-
- **`[allGreen, idle]`** — both. The
|
|
519
|
+
- **`[allGreen, idle]`** — both. The Step Agent reads `order.cause` (`'allGreen'` or
|
|
433
520
|
`'idle'`) to branch.
|
|
434
521
|
|
|
435
522
|
```yaml
|
|
@@ -446,7 +533,7 @@ carry an empty input fingerprint, so a commit can never satisfy it, and
|
|
|
446
533
|
`owenloop lint` hard-errors on it. Declare the step's output under
|
|
447
534
|
`produces:`/`generates:` only.
|
|
448
535
|
|
|
449
|
-
**Alarms.** A
|
|
536
|
+
**Alarms.** A Step Agent that needs a heartbeat or a deadline can call
|
|
450
537
|
`engine.setAlarm(workflow, step, at)` with an absolute timestamp — it overrides the
|
|
451
538
|
relative `idleAfter` window and survives a process restart.
|
|
452
539
|
`engine.nextAlarm(workflow)` tells an external scheduler when to wake the instance.
|
|
@@ -486,13 +573,17 @@ rather than inlining the payload itself.
|
|
|
486
573
|
|
|
487
574
|
Don't put credentials or secrets in an artifact value. Values are persisted
|
|
488
575
|
as plaintext in the SQLite store (no encryption at rest) and are copied
|
|
489
|
-
verbatim
|
|
490
|
-
|
|
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.
|
|
491
578
|
|
|
492
579
|
Those values are also *retained*, not just transiently persisted: every
|
|
493
580
|
artifact version is kept (the store never overwrites a prior version in place),
|
|
494
|
-
and every run's issued order packet —
|
|
495
|
-
— is written to the SQLite `run` table
|
|
496
|
-
|
|
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
|
|
497
588
|
therefore lives on in the database until the file itself is disposed of — see
|
|
498
589
|
[Storage](../README.md#storage) for the operator's disposal responsibility.
|