owenloop 0.5.3 → 0.5.5
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 +25 -0
- package/README.md +6 -2
- package/dist/packages/work/src/agent/brief.d.ts +6 -0
- package/dist/packages/work/src/agent/brief.js +102 -2
- package/dist/packages/work/src/agent/loop.d.ts +10 -1
- package/dist/packages/work/src/agent/loop.js +28 -0
- package/dist/packages/work/src/agent/workdir.d.ts +22 -0
- package/dist/packages/work/src/agent/workdir.js +80 -0
- package/dist/packages/work/src/exec/loop.d.ts +13 -1
- package/dist/packages/work/src/exec/loop.js +184 -9
- package/dist/packages/work/src/harness/child-env.js +8 -0
- package/dist/packages/work/src/harness/claude.js +25 -6
- package/dist/packages/work/src/harness/codex.js +7 -0
- package/dist/packages/work/src/harness/contract.d.ts +22 -3
- package/dist/packages/work/src/harness/contract.js +22 -3
- package/dist/packages/work/src/hold/mcp.d.ts +11 -2
- package/dist/packages/work/src/hold/mcp.js +69 -2
- package/dist/packages/work/src/hub/client.d.ts +8 -1
- package/dist/packages/work/src/hub/client.js +1 -0
- package/dist/packages/work/src/hub/types.d.ts +29 -0
- package/dist/packages/work/src/roles/agent-run.js +9 -1
- package/dist/packages/work/src/roles/exec.js +9 -0
- package/dist/packages/work/src/roles/shift.js +9 -1
- package/dist/packages/work/src/settings/settings.d.ts +32 -5
- package/dist/packages/work/src/settings/settings.js +37 -12
- package/dist/packages/work/src/shift/runtime.d.ts +7 -0
- package/dist/packages/work/src/shift/runtime.js +29 -4
- package/dist/packages/work/src/shift/spawn.d.ts +12 -2
- package/dist/packages/work/src/shift/spawn.js +16 -3
- package/dist/src/cli.js +257 -7
- package/dist/src/config-dir.d.ts +62 -0
- package/dist/src/config-dir.js +87 -0
- package/dist/src/crypto/trust-roots.d.ts +8 -4
- package/dist/src/crypto/trust-roots.js +18 -12
- package/dist/src/defs.js +57 -16
- package/dist/src/engine.d.ts +46 -1
- package/dist/src/engine.js +97 -3
- package/dist/src/hub.d.ts +5 -1
- package/dist/src/hub.js +7 -8
- package/dist/src/index.d.ts +1 -1
- package/dist/src/index.js +1 -1
- package/dist/src/model.d.ts +29 -5
- package/dist/src/model.js +63 -14
- package/dist/src/paths.d.ts +47 -4
- package/dist/src/paths.js +36 -5
- package/dist/src/types.d.ts +8 -2
- package/dist/src/work-settings.d.ts +8 -5
- package/dist/src/work-settings.js +15 -12
- package/docs/authoring.md +40 -13
- package/docs/bundles.md +9 -0
- package/docs/cli.md +155 -24
- package/docs/crypto.md +8 -8
- package/docs/design.md +20 -2
- package/docs/embedding.md +5 -4
- package/docs/wire-contracts.md +3 -2
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/dist/src/paths.d.ts
CHANGED
|
@@ -37,13 +37,56 @@ export interface WorkdirFromParts {
|
|
|
37
37
|
stem: string;
|
|
38
38
|
path: string;
|
|
39
39
|
mode: ConsumeMode;
|
|
40
|
+
/**
|
|
41
|
+
* Where the stem was found, which decides where the ENGINE reads the value.
|
|
42
|
+
*
|
|
43
|
+
* - `consume` — the stem names one of the step's own consumes. The value
|
|
44
|
+
* comes out of the resolved consume map for the firing.
|
|
45
|
+
* - `input` — the stem names one of the DEFINITION's declared inputs and
|
|
46
|
+
* the step does not consume it. The value comes out of the instance's
|
|
47
|
+
* artifact table, and the firing defers while that input is still owed.
|
|
48
|
+
*
|
|
49
|
+
* A consume always wins: the loop below tries consumes first at every split
|
|
50
|
+
* boundary, so a step that genuinely consumes an input keeps the old
|
|
51
|
+
* behaviour and nothing about an existing def changes meaning.
|
|
52
|
+
*/
|
|
53
|
+
source: 'consume' | 'input';
|
|
40
54
|
}
|
|
41
55
|
/**
|
|
42
|
-
* Split a workdirFrom expression by the longest prefix that names one of
|
|
43
|
-
* step's own consumes
|
|
44
|
-
*
|
|
56
|
+
* Split a workdirFrom expression by the longest prefix that names either one of
|
|
57
|
+
* the step's own consumes or one of the definition's declared inputs. Artifact
|
|
58
|
+
* stems may contain dots, so those two name lists are the closed grammar that
|
|
59
|
+
* makes the split deterministic at def-load time.
|
|
60
|
+
*
|
|
61
|
+
* ## Why an input stem is admissible, when the value becomes a filesystem path
|
|
62
|
+
*
|
|
63
|
+
* `validateDef` used to require the stem be a plain CONSUME, on the stated
|
|
64
|
+
* grounds that the value must have "passed the engine's consume-side
|
|
65
|
+
* verification gate before a worker can cd into it". That reasoning does not
|
|
66
|
+
* survive contact with what actually crosses the wire:
|
|
67
|
+
*
|
|
68
|
+
* - The engine resolves `workdirFrom` ITSELF, inside the claim transaction
|
|
69
|
+
* (`engine.ts`, `emitOrder`), and ships the resolved STRING as
|
|
70
|
+
* `OrderPacket.workdir` — declared in `packages/work/src/hub/types.ts` as an
|
|
71
|
+
* "Opaque location hint — the worker's cwd when set".
|
|
72
|
+
* - Nothing verifies that field. `consumesProof` covers `order.consumes`
|
|
73
|
+
* entries and only those (`consumed-verifier.ts`, `parseProofMap`), and the
|
|
74
|
+
* command worker takes `order.workdir ?? opts.cwd` with no check at all
|
|
75
|
+
* (`packages/work/src/exec/loop.ts`).
|
|
76
|
+
*
|
|
77
|
+
* So the consume gate never protected the cwd at runtime — by the time the
|
|
78
|
+
* value reaches a worker it is an unverified string in an unverified field
|
|
79
|
+
* either way. The old rule constrained who may AUTHOR the value (a producer
|
|
80
|
+
* step) rather than what a worker will trust, and this widens that authorship
|
|
81
|
+
* to include the human who starts the run. Both are inside the same trust
|
|
82
|
+
* boundary: principals authorized to start or serve runs on this hub.
|
|
83
|
+
*
|
|
84
|
+
* What actually bounds the cwd is machine-side and belongs to the operator, not
|
|
85
|
+
* to the def — a shift refuses an order whose workdir falls outside the roots
|
|
86
|
+
* its operator declared. That check is the runtime protection; this grammar is
|
|
87
|
+
* an authoring question.
|
|
45
88
|
*/
|
|
46
|
-
export declare function parseWorkdirFrom(raw: string, consumes: readonly ConsumePattern[]): WorkdirFromParts | null;
|
|
89
|
+
export declare function parseWorkdirFrom(raw: string, consumes: readonly ConsumePattern[], inputs?: readonly string[]): WorkdirFromParts | null;
|
|
47
90
|
/** Parse a produce declaration. */
|
|
48
91
|
export declare function parseProduce(raw: string): ProducePattern;
|
|
49
92
|
/**
|
package/dist/src/paths.js
CHANGED
|
@@ -65,11 +65,40 @@ export function parseConsume(raw) {
|
|
|
65
65
|
return { raw: r, mode: 'plain', stem: r, suffix: '' };
|
|
66
66
|
}
|
|
67
67
|
/**
|
|
68
|
-
* Split a workdirFrom expression by the longest prefix that names one of
|
|
69
|
-
* step's own consumes
|
|
70
|
-
*
|
|
68
|
+
* Split a workdirFrom expression by the longest prefix that names either one of
|
|
69
|
+
* the step's own consumes or one of the definition's declared inputs. Artifact
|
|
70
|
+
* stems may contain dots, so those two name lists are the closed grammar that
|
|
71
|
+
* makes the split deterministic at def-load time.
|
|
72
|
+
*
|
|
73
|
+
* ## Why an input stem is admissible, when the value becomes a filesystem path
|
|
74
|
+
*
|
|
75
|
+
* `validateDef` used to require the stem be a plain CONSUME, on the stated
|
|
76
|
+
* grounds that the value must have "passed the engine's consume-side
|
|
77
|
+
* verification gate before a worker can cd into it". That reasoning does not
|
|
78
|
+
* survive contact with what actually crosses the wire:
|
|
79
|
+
*
|
|
80
|
+
* - The engine resolves `workdirFrom` ITSELF, inside the claim transaction
|
|
81
|
+
* (`engine.ts`, `emitOrder`), and ships the resolved STRING as
|
|
82
|
+
* `OrderPacket.workdir` — declared in `packages/work/src/hub/types.ts` as an
|
|
83
|
+
* "Opaque location hint — the worker's cwd when set".
|
|
84
|
+
* - Nothing verifies that field. `consumesProof` covers `order.consumes`
|
|
85
|
+
* entries and only those (`consumed-verifier.ts`, `parseProofMap`), and the
|
|
86
|
+
* command worker takes `order.workdir ?? opts.cwd` with no check at all
|
|
87
|
+
* (`packages/work/src/exec/loop.ts`).
|
|
88
|
+
*
|
|
89
|
+
* So the consume gate never protected the cwd at runtime — by the time the
|
|
90
|
+
* value reaches a worker it is an unverified string in an unverified field
|
|
91
|
+
* either way. The old rule constrained who may AUTHOR the value (a producer
|
|
92
|
+
* step) rather than what a worker will trust, and this widens that authorship
|
|
93
|
+
* to include the human who starts the run. Both are inside the same trust
|
|
94
|
+
* boundary: principals authorized to start or serve runs on this hub.
|
|
95
|
+
*
|
|
96
|
+
* What actually bounds the cwd is machine-side and belongs to the operator, not
|
|
97
|
+
* to the def — a shift refuses an order whose workdir falls outside the roots
|
|
98
|
+
* its operator declared. That check is the runtime protection; this grammar is
|
|
99
|
+
* an authoring question.
|
|
71
100
|
*/
|
|
72
|
-
export function parseWorkdirFrom(raw, consumes) {
|
|
101
|
+
export function parseWorkdirFrom(raw, consumes, inputs = []) {
|
|
73
102
|
const r = raw.trim();
|
|
74
103
|
for (let boundary = r.lastIndexOf('.'); boundary > 0; boundary = r.lastIndexOf('.', boundary - 1)) {
|
|
75
104
|
const stem = r.slice(0, boundary);
|
|
@@ -78,7 +107,9 @@ export function parseWorkdirFrom(raw, consumes) {
|
|
|
78
107
|
continue;
|
|
79
108
|
const consume = consumes.find((c) => c.stem === stem);
|
|
80
109
|
if (consume)
|
|
81
|
-
return { raw: r, stem, path, mode: consume.mode };
|
|
110
|
+
return { raw: r, stem, path, mode: consume.mode, source: 'consume' };
|
|
111
|
+
if (inputs.includes(stem))
|
|
112
|
+
return { raw: r, stem, path, mode: 'plain', source: 'input' };
|
|
82
113
|
}
|
|
83
114
|
return null;
|
|
84
115
|
}
|
package/dist/src/types.d.ts
CHANGED
|
@@ -31,9 +31,15 @@ export type Author = 'engine' | 'human' | string;
|
|
|
31
31
|
* - `invalidated-irreversible`: the artifact was rejected-and-held because its inputs
|
|
32
32
|
* moved and its producer step declared `effect: { idempotent: false, onInvalidate: 'escalate' }`.
|
|
33
33
|
* The producer is NOT auto-eligible to re-fire; a human must intervene (retry / fix upstream).
|
|
34
|
+
* - `question`: the producing step ASKED a human and stopped, via `Engine.ask`.
|
|
35
|
+
* Holds exactly like `invalidated-irreversible` — the producer is not auto-eligible,
|
|
36
|
+
* so the step does not spin re-answering its own unanswered question — but it is a
|
|
37
|
+
* separate kind because the CAUSE is different and the audit trail should say so:
|
|
38
|
+
* nothing moved upstream, an agent decided it could not proceed honestly.
|
|
39
|
+
* Counts toward NO stall budget. A question is not a failed attempt.
|
|
34
40
|
*/
|
|
35
|
-
export type RejectKind = 'judgment' | 'structural' | 'validation' | 'invalidated-irreversible' | 'exclusive';
|
|
36
|
-
export type ReasonAction = 'reject' | 'retract' | 'skip' | 'reopen' | 'retry' | 'born-rejected' | 'schema-reject' | 'pinned';
|
|
41
|
+
export type RejectKind = 'judgment' | 'structural' | 'validation' | 'invalidated-irreversible' | 'question' | 'exclusive';
|
|
42
|
+
export type ReasonAction = 'reject' | 'retract' | 'skip' | 'reopen' | 'retry' | 'ask' | 'born-rejected' | 'schema-reject' | 'pinned';
|
|
37
43
|
/** A JSON Schema, as authored in a definition: an object, or a boolean (allow/deny all). */
|
|
38
44
|
export type JsonSchema = Record<string, unknown> | boolean;
|
|
39
45
|
/** One entry in an artifact's append-only reason thread (design §4). */
|
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
* execution settings file writer — the ONE place the root `owenloop` CLI writes
|
|
3
3
|
* into the execution-side settings file.
|
|
4
4
|
*
|
|
5
|
-
* `owenloop work` reads its settings from `$
|
|
6
|
-
*
|
|
5
|
+
* `owenloop work` reads its settings from `$OWENLOOP_CONFIG_DIR/settings.json`
|
|
6
|
+
* (else `$XDG_CONFIG_HOME/owenloop/settings.json`, else
|
|
7
|
+
* `$HOME/.config/owenloop/settings.json`) and, by design,
|
|
7
8
|
* NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
|
|
8
9
|
* `owenloop setup` can point `owenloop work` at the hub it just authenticated
|
|
9
10
|
* against.
|
|
@@ -23,9 +24,11 @@
|
|
|
23
24
|
* util.ts — no CLI/engine closure.
|
|
24
25
|
*/
|
|
25
26
|
/**
|
|
26
|
-
* The execution settings file path for this environment
|
|
27
|
-
*
|
|
28
|
-
*
|
|
27
|
+
* The execution settings file path for this environment, through the one shared
|
|
28
|
+
* ladder in `config-dir.ts`: `OWENLOOP_CONFIG_DIR` (absolute, used verbatim)
|
|
29
|
+
* wins over `$XDG_CONFIG_HOME/owenloop`, which wins over
|
|
30
|
+
* `$HOME/.config/owenloop`. Throws as a `CliError` when no rung yields a value,
|
|
31
|
+
* so the CLI reports it as an operator error rather than a crash.
|
|
29
32
|
*/
|
|
30
33
|
export declare function owenloopSettingsPath(env: Record<string, string | undefined>): string;
|
|
31
34
|
/**
|
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
* execution settings file writer — the ONE place the root `owenloop` CLI writes
|
|
3
3
|
* into the execution-side settings file.
|
|
4
4
|
*
|
|
5
|
-
* `owenloop work` reads its settings from `$
|
|
6
|
-
*
|
|
5
|
+
* `owenloop work` reads its settings from `$OWENLOOP_CONFIG_DIR/settings.json`
|
|
6
|
+
* (else `$XDG_CONFIG_HOME/owenloop/settings.json`, else
|
|
7
|
+
* `$HOME/.config/owenloop/settings.json`) and, by design,
|
|
7
8
|
* NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
|
|
8
9
|
* `owenloop setup` can point `owenloop work` at the hub it just authenticated
|
|
9
10
|
* against.
|
|
@@ -24,21 +25,23 @@
|
|
|
24
25
|
*/
|
|
25
26
|
import { existsSync, mkdirSync, readFileSync } from 'node:fs';
|
|
26
27
|
import { dirname, join } from 'node:path';
|
|
28
|
+
import { owenloopConfigDir } from "./config-dir.js";
|
|
27
29
|
import { writeFileAtomic } from "./hub.js";
|
|
28
30
|
import { CliError } from "./util.js";
|
|
29
31
|
/**
|
|
30
|
-
* The execution settings file path for this environment
|
|
31
|
-
*
|
|
32
|
-
*
|
|
32
|
+
* The execution settings file path for this environment, through the one shared
|
|
33
|
+
* ladder in `config-dir.ts`: `OWENLOOP_CONFIG_DIR` (absolute, used verbatim)
|
|
34
|
+
* wins over `$XDG_CONFIG_HOME/owenloop`, which wins over
|
|
35
|
+
* `$HOME/.config/owenloop`. Throws as a `CliError` when no rung yields a value,
|
|
36
|
+
* so the CLI reports it as an operator error rather than a crash.
|
|
33
37
|
*/
|
|
34
38
|
export function owenloopSettingsPath(env) {
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
throw new CliError('cannot locate a config directory for execution settings: set HOME or XDG_CONFIG_HOME');
|
|
39
|
+
try {
|
|
40
|
+
return join(owenloopConfigDir(env), 'settings.json');
|
|
41
|
+
}
|
|
42
|
+
catch (err) {
|
|
43
|
+
throw new CliError(`cannot locate a config directory for execution settings: ${err instanceof Error ? err.message : String(err)}`);
|
|
44
|
+
}
|
|
42
45
|
}
|
|
43
46
|
/**
|
|
44
47
|
* Read and parse the execution settings file at `path`.
|
package/docs/authoring.md
CHANGED
|
@@ -113,36 +113,61 @@ a literal model id. Pin an exact model when you need reproducibility — just
|
|
|
113
113
|
know the def is now host-specific, on purpose. Omit `model:` entirely and the
|
|
114
114
|
dispatcher uses its default.
|
|
115
115
|
|
|
116
|
-
## `workdirFrom:` — resolve a local workdir from a consumed value
|
|
116
|
+
## `workdirFrom:` — resolve a local workdir from a consumed value or a declared input
|
|
117
117
|
|
|
118
|
-
`workdirFrom:` sets the existing `Order.workdir` from a nested field in a green
|
|
119
|
-
|
|
118
|
+
`workdirFrom:` sets the existing `Order.workdir` from a nested field in a green
|
|
119
|
+
artifact. The grammar is `<stem>.<dotted.value.path>`, and the stem may name
|
|
120
|
+
either one of the step's own plain consumes or one of the definition's declared
|
|
121
|
+
inputs:
|
|
120
122
|
|
|
121
123
|
```yaml
|
|
124
|
+
inputs:
|
|
125
|
+
- name: target # where the run should do its work
|
|
126
|
+
seedOwed: true
|
|
122
127
|
steps:
|
|
123
128
|
- name: provisioner
|
|
124
|
-
consumes: [
|
|
129
|
+
consumes: [] # a command step that creates the worktree
|
|
125
130
|
produces: [workspace]
|
|
131
|
+
workdirFrom: target.path
|
|
126
132
|
- name: builder
|
|
127
133
|
consumes: [workspace]
|
|
128
134
|
produces: [pr]
|
|
129
135
|
workdirFrom: workspace.payload.worktreePath
|
|
130
136
|
```
|
|
131
137
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
138
|
+
A consume always wins when a stem could be read either way, so a step that
|
|
139
|
+
consumes the artifact it takes its workdir from keeps reading out of that
|
|
140
|
+
firing's consume binding. The consume must be plain rather than map (`[$i]`) or
|
|
141
|
+
reduce (`[*]`). The engine resolves the longest matching stem prefix when an
|
|
135
142
|
artifact stem itself contains dots. `workdir:` and `workdirFrom:` are mutually
|
|
136
143
|
exclusive.
|
|
137
144
|
|
|
138
|
-
|
|
145
|
+
Reach for the **input** form when the step cannot consume the value. The clearest
|
|
146
|
+
case is a `command` step: command orders are gated with the hard consumed-artifact
|
|
147
|
+
rule, which refuses any consumed value that carries no producer signature — and a
|
|
148
|
+
human-supplied seed input never has one. Naming the input in `workdirFrom:`
|
|
149
|
+
routes the value through `Order.workdir`, a spawn parameter the engine resolves
|
|
150
|
+
itself, rather than through `consumes`. This is also the only way a
|
|
151
|
+
run-supplied value reaches a `command:` string's context, because a command's
|
|
152
|
+
argv is passed to `/bin/sh -c` verbatim and is never interpolated.
|
|
153
|
+
|
|
154
|
+
Naming an input creates an ordering edge without a consume: while that input is
|
|
155
|
+
still owed, the firing defers with `workdir-unresolved` and detail
|
|
156
|
+
`input '<name>' is not green yet`, exactly as a consume would have made it wait.
|
|
157
|
+
The value does not appear in `Order.consumes`.
|
|
158
|
+
|
|
159
|
+
At order-build time the engine walks the resolved value using the dotted path.
|
|
139
160
|
A missing field, non-object intermediate, array, non-string final value, empty
|
|
140
161
|
string, or whitespace-only string defers the firing with reason
|
|
141
162
|
`workdir-unresolved`; the engine emits no order and inserts no run. The engine
|
|
142
163
|
passes a valid path through unchanged: the engine does not resolve or normalize
|
|
143
164
|
a relative path and does not change the worker's current-directory semantics.
|
|
144
165
|
The producer and worker must therefore run on the same machine. A permanently
|
|
145
|
-
unresolvable path remains deferred until
|
|
166
|
+
unresolvable path remains deferred until a valid value arrives.
|
|
167
|
+
|
|
168
|
+
`Order.workdir` is an opaque location hint that no proof covers, whichever form
|
|
169
|
+
produced it. What bounds where a worker may actually run is machine-side and
|
|
170
|
+
belongs to the operator running the shift, not to the definition.
|
|
146
171
|
|
|
147
172
|
## `executor:` — declaring the executor
|
|
148
173
|
|
|
@@ -269,10 +294,12 @@ indirection. Two consequences of the local filter are worth stating plainly:
|
|
|
269
294
|
permanently unclaimed step is caught rather than silently stuck.
|
|
270
295
|
|
|
271
296
|
A `workdirFrom` firing can also remain deferred forever with
|
|
272
|
-
`workdir-unresolved`. That reason means
|
|
273
|
-
|
|
274
|
-
non-empty string. Fix
|
|
275
|
-
|
|
297
|
+
`workdir-unresolved`. That reason means no usable nested path has been supplied:
|
|
298
|
+
the artifact is not green yet, or its value is missing, has an invalid shape, or
|
|
299
|
+
is not a non-empty string. Fix whoever supplies that artifact — the producing
|
|
300
|
+
step for a consumed stem, or the human starting the run for a declared input.
|
|
301
|
+
Changing the consumer's worker does not bypass the engine's workdir resolution
|
|
302
|
+
check.
|
|
276
303
|
|
|
277
304
|
`capabilities:` is distinct from [`executor:`](#executor--declaring-the-executor):
|
|
278
305
|
`executor:` says what *kind* of executor should run an order once it's claimed;
|
package/docs/bundles.md
CHANGED
|
@@ -263,6 +263,15 @@ command inherits the directory the operator was standing in when they ran
|
|
|
263
263
|
`owenloop shift start`. Nothing is enforced today: a future release will
|
|
264
264
|
require a step to declare that inheritance explicitly.
|
|
265
265
|
|
|
266
|
+
`workdirFrom:` is how a run tells a command step *where* to work. Its stem may
|
|
267
|
+
name a declared input, not only a consumed artifact, and that is the only
|
|
268
|
+
channel a run-supplied value has into a command step: `consumes:` is refused for
|
|
269
|
+
a human seed by the hard consumed-artifact gate above, and the `command:` string
|
|
270
|
+
reaches `/bin/sh -c` as authored bytes with no interpolation. A command step
|
|
271
|
+
that would otherwise be pinned to the one directory its shift was started in can
|
|
272
|
+
therefore take a project root per run — see
|
|
273
|
+
[authoring.md](authoring.md#workdirfrom--resolve-a-local-workdir-from-a-consumed-value-or-a-declared-input).
|
|
274
|
+
|
|
266
275
|
**Where the fallback is recorded.** When it fires, `owenloop work exec` writes
|
|
267
276
|
one warning per spawn naming the step, the workflow and run ids, and the
|
|
268
277
|
resolved absolute path. That warning goes to the exec worker's own stderr.
|
package/docs/cli.md
CHANGED
|
@@ -170,9 +170,18 @@ accepted `shift next` records attendance and makes the next presence ping due,
|
|
|
170
170
|
but attendance is advisory and observability-only. Attendance never changes
|
|
171
171
|
routing, dispatch, or lease behavior.
|
|
172
172
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
173
|
+
<a id="config-dir"></a>
|
|
174
|
+
The execution settings file is `<config>/settings.json`. Throughout this
|
|
175
|
+
document `<config>` is owenloop's own config directory, resolved from the
|
|
176
|
+
environment by this ladder, highest first:
|
|
177
|
+
|
|
178
|
+
1. `$OWENLOOP_CONFIG_DIR` when set to a non-blank ABSOLUTE path — used verbatim,
|
|
179
|
+
with no `owenloop` segment appended;
|
|
180
|
+
2. `$XDG_CONFIG_HOME/owenloop` when `XDG_CONFIG_HOME` is non-blank;
|
|
181
|
+
3. `$HOME/.config/owenloop`.
|
|
182
|
+
|
|
183
|
+
The same directory holds `credentials.json`, `allowed_signers`, `org-root.pub`,
|
|
184
|
+
`roster/`, and `revocations/`.
|
|
176
185
|
|
|
177
186
|
### `shift start <crew...>`
|
|
178
187
|
|
|
@@ -180,6 +189,7 @@ The execution settings file is `$XDG_CONFIG_HOME/owenloop/settings.json` when
|
|
|
180
189
|
owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
|
|
181
190
|
[--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
|
|
182
191
|
[--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
|
|
192
|
+
[--work-root <dir>]...
|
|
183
193
|
```
|
|
184
194
|
|
|
185
195
|
At least one named crew is required unless `--all` is present. `--all` and
|
|
@@ -200,6 +210,7 @@ one loop sweep and exits instead of keeping the foreground daemon running.
|
|
|
200
210
|
| `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
|
|
201
211
|
| `--state-dir <p>` | socket and child-state root; precedence is flag, then `OWENLOOP_STATE_DIR`, then `settings.stateDir`, then `$XDG_STATE_HOME/owenloop/exec`, then `$HOME/.local/state/owenloop/exec`; the socket is `shift.sock` inside this directory |
|
|
202
212
|
| `--log-dir <p>` | where `shift.log` and each `<run>.log` are written; precedence is flag, then `OWENLOOP_SHIFT_LOG_DIR`, then `settings.shiftLogDir`, then the resolved state directory |
|
|
213
|
+
| `--work-root <dir>` | **repeatable.** restrict this machine to orders whose working directory is inside one of these roots; precedence is the flags, then `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (a `:`-separated list), then `settings.allowedWorkdirRoots`. Each rung REPLACES the one below it rather than extending it. No rung set anywhere ⇒ **no restriction**, which is the default |
|
|
203
214
|
| `--log-max-age <ms>` | worker-log retention, swept once at startup; precedence is flag, then `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, then `settings.shiftLogMaxAgeMs`, then `1209600000` (14 days). `0` reaps every completed run's log at the next startup; there is no value that disables the sweep, and `shift.log` is never reaped |
|
|
204
215
|
|
|
205
216
|
**On-disk logs.** A running shift appends its dispatch record to
|
|
@@ -210,6 +221,38 @@ dispatch: the shift reports it once on stderr and serves with logging disabled.
|
|
|
210
221
|
Full field-by-field contract, retention rules, and uploader notes in
|
|
211
222
|
[`docs/shift-logs.md`](shift-logs.md).
|
|
212
223
|
|
|
224
|
+
**Where a shift will do work.** A shift is not bound to a project: it is an
|
|
225
|
+
orchestrator that runs whatever its crews are offered. `--work-root` is how the
|
|
226
|
+
person who owns the machine bounds that — it is a **local** policy, declared at
|
|
227
|
+
the shift, and the hub is never asked and never informed in advance.
|
|
228
|
+
|
|
229
|
+
The check happens in the WORKER, not in dispatch. The shift's `whats_next` sweep
|
|
230
|
+
receives a `WorkOrder`, which carries no working directory at all; only the
|
|
231
|
+
`OrderPacket` a worker fetches with `get_order` has one. So `owenloop work exec`
|
|
232
|
+
and `owenloop work agent-run` each resolve the roots themselves — from
|
|
233
|
+
`OWENLOOP_ALLOWED_WORKDIR_ROOTS`, which the shift exports into every child it
|
|
234
|
+
spawns, or from the settings file when run by hand — and refuse there.
|
|
235
|
+
|
|
236
|
+
A refusal is a **release**, not a failure. The order is valid; this machine is
|
|
237
|
+
simply not configured to host that tree. The worker releases its claim, exits
|
|
238
|
+
non-zero, and writes one line to `<log-dir>/<run>.log` naming the directory and
|
|
239
|
+
the roots. The order returns to the hub's pickup window, where a machine that
|
|
240
|
+
*is* configured for that tree can take it.
|
|
241
|
+
|
|
242
|
+
Only a workdir the ORDER names is checked. A step that declares neither
|
|
243
|
+
`workdir:` nor `workdirFrom:` falls back to a directory the operator already
|
|
244
|
+
controls — the shift's own launch directory for a command step, or
|
|
245
|
+
`<workRoot>/<workflow>/<run>/` for an agent step — and is never denied.
|
|
246
|
+
|
|
247
|
+
`--work-root` is not `--work-root`'s neighbour `workRoot`. `workRoot` (settings,
|
|
248
|
+
`OWENLOOP_WORK_ROOT`) is the ONE directory owenloop **creates** per-run
|
|
249
|
+
directories under. `--work-root` / `allowedWorkdirRoots` is the SET of
|
|
250
|
+
directories an order is **allowed to name**. Neither derives from the other.
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
owenloop shift start build --work-root ~/code --work-root /srv/work
|
|
254
|
+
```
|
|
255
|
+
|
|
213
256
|
**One harness per shift.** A shift has no per-order harness switch and no
|
|
214
257
|
`--harness` flag. It never puts `--harness` on a worker's command line; each
|
|
215
258
|
`agent-run` child resolves its own adapter, in this order:
|
|
@@ -225,25 +268,46 @@ starts the shift and every agent order that shift dispatches runs on that
|
|
|
225
268
|
adapter. To run two adapters at once, start two shifts:
|
|
226
269
|
|
|
227
270
|
```bash
|
|
228
|
-
OWENLOOP_HARNESS=claude-code
|
|
271
|
+
OWENLOOP_HARNESS=claude-code OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/claude/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/claude
|
|
229
272
|
```
|
|
230
273
|
|
|
231
274
|
```bash
|
|
232
|
-
OWENLOOP_HARNESS=codex
|
|
275
|
+
OWENLOOP_HARNESS=codex OWENLOOP_CONFIG_DIR=~/.config/owenloop-shifts/codex/owenloop owenloop shift start build --state-dir ~/.local/state/owenloop/codex
|
|
233
276
|
```
|
|
234
277
|
|
|
235
278
|
Both shifts may serve the SAME crew. The hub does not route by harness — it
|
|
236
279
|
offers an order to any shift whose crew is bound to the order's capability, and
|
|
237
280
|
whichever shift claims it first runs it on its own adapter.
|
|
238
281
|
|
|
239
|
-
**
|
|
240
|
-
settings file resolves from
|
|
282
|
+
**A per-shift config directory is not optional when the adapters differ.** The
|
|
283
|
+
settings file resolves from the config directory (see above), and it carries
|
|
241
284
|
`capabilityModels` — a map of composed capability to `{model, effort}` whose
|
|
242
285
|
model ids are strings the SHIFT'S OWN adapter accepts. Two shifts on different
|
|
243
286
|
adapters need different model ids for the same capability, so they need
|
|
244
|
-
different settings files, so they need different
|
|
245
|
-
|
|
246
|
-
|
|
287
|
+
different settings files, so they need different config directories. A shared
|
|
288
|
+
config directory would give both shifts one adapter's model ids, and the shift
|
|
289
|
+
holding the wrong adapter fails at the vendor API on its first order.
|
|
290
|
+
|
|
291
|
+
**Use `OWENLOOP_CONFIG_DIR` for this, not `XDG_CONFIG_HOME`.** Both resolve the
|
|
292
|
+
settings file, and `OWENLOOP_CONFIG_DIR` wins — but `XDG_CONFIG_HOME` is a
|
|
293
|
+
machine-wide contract that `gh`, `git`, `gcloud`, `npm`, and most of the rest of
|
|
294
|
+
a developer's toolchain also read, and a shift spreads its ENTIRE environment
|
|
295
|
+
into every worker it dispatches, which passes it on to every command step's
|
|
296
|
+
child process. Scoping a shift with `XDG_CONFIG_HOME` therefore relocates the
|
|
297
|
+
configuration of every tool the workflow's own scripts shell out to. Measured,
|
|
298
|
+
not theorized: on one delivery run this stranded `gh`'s stored credential, and
|
|
299
|
+
the workflow's merge gate spent its full 40-minute wall clock deferring on a CI
|
|
300
|
+
probe that could not authenticate, followed by four consecutive merge failures
|
|
301
|
+
reading `could not resolve a pull request handle for the branch`. Nothing was
|
|
302
|
+
wrong with either script. `OWENLOOP_CONFIG_DIR` scopes owenloop and only
|
|
303
|
+
owenloop.
|
|
304
|
+
|
|
305
|
+
`OWENLOOP_CONFIG_DIR` names the owenloop config directory ITSELF — the directory
|
|
306
|
+
that directly holds `settings.json`, `credentials.json`, and `allowed_signers`.
|
|
307
|
+
No `owenloop` path segment is appended to it, unlike the `XDG_CONFIG_HOME` rung.
|
|
308
|
+
It must be an ABSOLUTE path: a relative one would resolve against whatever
|
|
309
|
+
working directory a step happens to have, and `workdirFrom` gives every step its
|
|
310
|
+
own.
|
|
247
311
|
|
|
248
312
|
Give each shift its own `--state-dir` as well. The state directory holds the
|
|
249
313
|
control socket (`shift.sock`), and a second shift starting against a socket
|
|
@@ -449,9 +513,8 @@ only the root `owenloop shift` command; `owenloop work` has no standing-daemon a
|
|
|
449
513
|
`hold --mcp` remains because the machine-attached hold mount still exists.
|
|
450
514
|
Run `owenloop work --help` for the full role-specific usage.
|
|
451
515
|
|
|
452
|
-
The execution settings file is
|
|
453
|
-
|
|
454
|
-
`$HOME/.config/owenloop/settings.json`.
|
|
516
|
+
The execution settings file is `<config>/settings.json` (see
|
|
517
|
+
[the config-directory ladder](#config-dir)).
|
|
455
518
|
|
|
456
519
|
| subcommand | what it does |
|
|
457
520
|
|---|---|
|
|
@@ -816,9 +879,8 @@ signed or explicitly unsigned sidecar.
|
|
|
816
879
|
### Definition publication policy
|
|
817
880
|
|
|
818
881
|
`defPolicy` is the local execution and installation policy for workflow
|
|
819
|
-
publication signatures. The settings file is
|
|
820
|
-
|
|
821
|
-
otherwise `$HOME/.config/owenloop/settings.json`. To set the policy in the
|
|
882
|
+
publication signatures. The settings file is `<config>/settings.json` (see
|
|
883
|
+
[the config-directory ladder](#config-dir)). To set the policy in the
|
|
822
884
|
settings file, write a JSON object such as:
|
|
823
885
|
|
|
824
886
|
```json
|
|
@@ -1022,9 +1084,8 @@ when `defPolicy=off`, and only then runs the origin check. Unsigned,
|
|
|
1022
1084
|
unverifiable, or invalid publication evidence never reaches the shell. An
|
|
1023
1085
|
origin mode of `off` and every policy-floor preset leave that gate unchanged.
|
|
1024
1086
|
|
|
1025
|
-
The local SSHSIG trust root is
|
|
1026
|
-
|
|
1027
|
-
`$HOME/.config/owenloop/allowed_signers` when `XDG_CONFIG_HOME` is blank. A
|
|
1087
|
+
The local SSHSIG trust root is `<config>/allowed_signers` (see
|
|
1088
|
+
[the config-directory ladder](#config-dir)). A
|
|
1028
1089
|
missing or malformed trust root is `unverifiable`, not `unsigned`.
|
|
1029
1090
|
|
|
1030
1091
|
### The two store roots
|
|
@@ -1261,7 +1322,7 @@ checks both journal locations and dispatches by journal version; a v2 store
|
|
|
1261
1322
|
journal uses `index.json` metadata and a v1 GitHub journal uses
|
|
1262
1323
|
`installed.json` ledger corroboration.
|
|
1263
1324
|
|
|
1264
|
-
## Hub (`login` / `connect` / `push` / `start` / `publish` / `logout`)
|
|
1325
|
+
## Hub (`login` / `connect` / `push` / `start` / `cancel` / `instance` / `publish` / `logout`)
|
|
1265
1326
|
|
|
1266
1327
|
These commands authenticate, publish, and start workflows on a hosted **hub** (default
|
|
1267
1328
|
`https://api.owenloop.com`). `login` and `logout` retain the generic resolver:
|
|
@@ -1325,6 +1386,77 @@ usage errors before credential or network access. The command does not claim,
|
|
|
1325
1386
|
dispatch, close, or otherwise drive work—the standing Shift discovers the run
|
|
1326
1387
|
through its normal crew inbox.
|
|
1327
1388
|
|
|
1389
|
+
### `cancel` — stop a running instance
|
|
1390
|
+
|
|
1391
|
+
`owenloop cancel <workflow>` sends `POST /api/cancel_run` and prints whether the
|
|
1392
|
+
instance was cancelled, its resulting status, and the runs whose leases were
|
|
1393
|
+
closed. `--reason <text>` is optional and recorded on the hub's audit row; like
|
|
1394
|
+
`--crew`/`--title` on `start`, a bare `--reason` or `--reason=` is a local usage
|
|
1395
|
+
error before credential or network access. Hub resolution matches `start`: the
|
|
1396
|
+
project binding wins, and an explicit `--hub` must agree with it.
|
|
1397
|
+
|
|
1398
|
+
This is the counterpart to `start`, and the only local way out of a run that can
|
|
1399
|
+
no longer make progress — a step whose worktree was deleted, or an instance
|
|
1400
|
+
pinned to a def version its shift can no longer satisfy. Such a run is otherwise
|
|
1401
|
+
re-offered forever and permanently occupies one of a shift's dispatch slots,
|
|
1402
|
+
because nothing else on the machine can move it to a terminal state.
|
|
1403
|
+
|
|
1404
|
+
Three properties come from the hub verb, not from this command:
|
|
1405
|
+
|
|
1406
|
+
- **Human-role-only.** `cancel_run` has no agent-scope entry, so an agent
|
|
1407
|
+
credential is refused by the hub. `cancel` therefore always reads the `human`
|
|
1408
|
+
credential slot and does not accept `--as`.
|
|
1409
|
+
- **Idempotent.** Cancelling an instance that already reached a terminal state
|
|
1410
|
+
writes nothing and returns `cancelled: false` plus the state it found. That is
|
|
1411
|
+
a success and exits 0 — a retried cancel must not look like a failure.
|
|
1412
|
+
- **Receipt says `failed`.** The receipt `outcome` union is only `done|failed`,
|
|
1413
|
+
so a cancel composes its receipt as `failed`. The true cancel fact lives in the
|
|
1414
|
+
instance's distinct `cancelled` status and an `action: 'cancel'` audit row.
|
|
1415
|
+
`cancel` prints the status rather than the receipt outcome, so its output does
|
|
1416
|
+
not imply the run failed on its own.
|
|
1417
|
+
|
|
1418
|
+
### `instance show` — read a hub instance's live state
|
|
1419
|
+
|
|
1420
|
+
`owenloop instance show <workflow>` sends `GET /api/status/:wf` and prints the
|
|
1421
|
+
instance's state: `done`, the `debts` it still owes, the steps that are
|
|
1422
|
+
`eligible` or `blocked`, the runs `inFlight`, and `defDrift`.
|
|
1423
|
+
|
|
1424
|
+
It answers the question no other local command can: **why is this run not
|
|
1425
|
+
moving?** Two of its fields are the entire diagnosis, and both are invisible
|
|
1426
|
+
from the outside because each one looks exactly like an idle shift:
|
|
1427
|
+
|
|
1428
|
+
- **`defDrift: true`** — a hub instance is PINNED to the def version it started
|
|
1429
|
+
on. Publishing a new bundle does not affect a run already in flight. This is
|
|
1430
|
+
the field that explains "I fixed the def and republished, and the run still
|
|
1431
|
+
does the old thing."
|
|
1432
|
+
- **`waitingOnCapabilities`** — a step whose capability has no crew bound is
|
|
1433
|
+
never offered to anyone. Present only when something is actually parked;
|
|
1434
|
+
`getStatus` omits the field otherwise, and `instance show` omits it too rather
|
|
1435
|
+
than printing `[]`, which would read as "asked, and the answer is none."
|
|
1436
|
+
|
|
1437
|
+
Naming, because two obvious names were already taken by different commands:
|
|
1438
|
+
|
|
1439
|
+
- `owenloop status` is the **local** engine's status and takes `--db`. It has no
|
|
1440
|
+
hub credential and rejects `--hub`.
|
|
1441
|
+
- `owenloop runs <workflow>` already lists runs from the **local** sqlite store.
|
|
1442
|
+
|
|
1443
|
+
`instance` is the hub's own word for a started workflow (`setInstanceStatus`,
|
|
1444
|
+
`listInstancesWithStatus`, `cancel_run`'s "already-terminal instance"), so the
|
|
1445
|
+
hub object and the local object keep separate commands instead of one command
|
|
1446
|
+
whose meaning flips on a flag.
|
|
1447
|
+
|
|
1448
|
+
**Only `show` exists, and that is a hub limitation.** `getStatus` is the one
|
|
1449
|
+
instance-read verb with a REST route. `listInstancesWithStatus` (which would
|
|
1450
|
+
back `instance list`) and `listReceipts` / `getReceiptDetail` (where a
|
|
1451
|
+
reviewer's reject reason actually lives) are exposed only over tRPC for the
|
|
1452
|
+
console. Reaching either from the CLI requires new routes in
|
|
1453
|
+
`apps/hub-edge/src/api/routes.ts` and a hub deploy. The subcommand form exists
|
|
1454
|
+
so they can arrive as `instance list` without renaming anything.
|
|
1455
|
+
|
|
1456
|
+
Like `cancel`, it reads the `human` slot, never consults `--as`, and resolves
|
|
1457
|
+
the hub through the project binding so an ambient `OWENLOOP_HUB` cannot redirect
|
|
1458
|
+
the read to a different control plane.
|
|
1459
|
+
|
|
1328
1460
|
**Publishing hub resolution.** `connect`, `push`, and `publish` resolve their
|
|
1329
1461
|
target in this order:
|
|
1330
1462
|
|
|
@@ -1334,9 +1466,8 @@ target in this order:
|
|
|
1334
1466
|
- with the file credential backend, exactly one origin containing a valid
|
|
1335
1467
|
human-slot credential is selected automatically;
|
|
1336
1468
|
- Keychain and external-command credential backends cannot enumerate their
|
|
1337
|
-
origins, so the validated `hubOrigin` in
|
|
1338
|
-
|
|
1339
|
-
`~/.config/owenloop/settings.json`) is used, and the requested credential
|
|
1469
|
+
origins, so the validated `hubOrigin` in `<config>/settings.json` (see
|
|
1470
|
+
[the config-directory ladder](#config-dir)) is used, and the requested credential
|
|
1340
1471
|
slot must exist there before the command proceeds.
|
|
1341
1472
|
4. If nothing safe resolves, the command exits 2 without network or publication
|
|
1342
1473
|
output effects.
|
|
@@ -1409,7 +1540,7 @@ empty `agent:ci` fails rather than quietly pushing as you. `logout` without
|
|
|
1409
1540
|
(`security`, service `owenloop:<hub origin>`, one item per slot, with the slot
|
|
1410
1541
|
name as the account) with the secret fed over stdin, never on the command line.
|
|
1411
1542
|
Elsewhere — or with `OWENLOOP_NO_KEYCHAIN=1` — it falls back to a `0600` file at
|
|
1412
|
-
|
|
1543
|
+
`<config>/credentials.json` (see [the config-directory ladder](#config-dir)) inside
|
|
1413
1544
|
a `0700` directory, keyed `hubs[origin][slot]`. Either way the token is never
|
|
1414
1545
|
written into the repo or a `.env`. `login`'s JSON reports `storage: "keychain" |
|
|
1415
1546
|
"file"` and `kind`, and prints **no token value** to stdout/stderr. A credential
|
package/docs/crypto.md
CHANGED
|
@@ -523,17 +523,16 @@ sidecar is checked against the bundle digest and the local `allowed_signers`
|
|
|
523
523
|
trust root. Origin verification is separate: `verifyOrigin` returns `absent`
|
|
524
524
|
when the origin sidecar is missing, `verified` only after DSSE signature, schema,
|
|
525
525
|
signer-key, and bundle-digest checks pass, and `unverifiable` or `invalid` for
|
|
526
|
-
the corresponding failures. The trust-root path is
|
|
527
|
-
`$
|
|
528
|
-
`XDG_CONFIG_HOME` is non-blank,
|
|
529
|
-
|
|
526
|
+
the corresponding failures. The trust-root path is `<config>/allowed_signers`, where `<config>` is
|
|
527
|
+
`$OWENLOOP_CONFIG_DIR` when set to a non-blank absolute path, else
|
|
528
|
+
`$XDG_CONFIG_HOME/owenloop` when `XDG_CONFIG_HOME` is non-blank, else
|
|
529
|
+
`$HOME/.config/owenloop`. A missing or malformed trust root produces the distinct
|
|
530
530
|
`unverifiable` verdict; a present signature that fails verification produces
|
|
531
531
|
`invalid`.
|
|
532
532
|
|
|
533
533
|
The execution and install policy is `defPolicy`, with built-in default `warn`.
|
|
534
|
-
Set `defPolicy` in the JSON settings file at
|
|
535
|
-
|
|
536
|
-
`$HOME/.config/owenloop/settings.json`), for example:
|
|
534
|
+
Set `defPolicy` in the JSON settings file at `<config>/settings.json` (same
|
|
535
|
+
ladder as the trust root above), for example:
|
|
537
536
|
|
|
538
537
|
```json
|
|
539
538
|
{
|
|
@@ -713,7 +712,8 @@ whole organization.
|
|
|
713
712
|
### Local anchor and envelope files
|
|
714
713
|
|
|
715
714
|
The optional filesystem loader derives paths from injected environment state:
|
|
716
|
-
`
|
|
715
|
+
`OWENLOOP_CONFIG_DIR` wins over `XDG_CONFIG_HOME`, which wins over `HOME`;
|
|
716
|
+
there is no ambient home-directory lookup.
|
|
717
717
|
The local layout is:
|
|
718
718
|
|
|
719
719
|
```text
|