owenloop 0.4.1 → 0.5.0
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 +26 -0
- package/README.md +58 -31
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -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 +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -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/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -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 +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -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 +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -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 +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -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/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -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 +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -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 +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -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 +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -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 +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -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 +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -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 +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{cli.d.ts → src/cli.d.ts} +18 -3
- package/dist/{cli.js → src/cli.js} +770 -114
- package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
- package/dist/{credentials.js → src/credentials.js} +14 -12
- package/dist/{defs.js → src/defs.js} +36 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +14 -14
- package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
- package/dist/{hub.js → src/hub.js} +370 -12
- package/dist/{index.d.ts → src/index.d.ts} +1 -1
- package/dist/{index.js → src/index.js} +1 -1
- package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
- package/dist/{mcp → src/mcp}/serve.js +168 -31
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +6 -9
- package/dist/{model.js → src/model.js} +1 -1
- package/dist/{types.d.ts → src/types.d.ts} +18 -18
- 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/authoring.md +93 -53
- package/docs/cli.md +597 -76
- package/docs/design.md +33 -33
- package/docs/embedding.md +10 -9
- 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 +17 -8
- /package/dist/{add.d.ts → src/add.d.ts} +0 -0
- /package/dist/{add.js → src/add.js} +0 -0
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{lock.d.ts → src/lock.d.ts} +0 -0
- /package/dist/{lock.js → src/lock.js} +0 -0
- /package/dist/{model.d.ts → src/model.d.ts} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /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
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /package/dist/{untar.js → src/untar.js} +0 -0
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What to spawn: the order to run. `run` IS the order id (hub verb contract);
|
|
3
|
+
* `workflow` pairs with it (every hub verb needs both). The hub `origin` is NOT
|
|
4
|
+
* here — it is captured by `createDefaultSpawner` (one hub per shift), so the
|
|
5
|
+
* loop, which knows only the order, calls the seam without carrying it.
|
|
6
|
+
*/
|
|
7
|
+
export interface SpawnSpec {
|
|
8
|
+
workflow: string;
|
|
9
|
+
run: string;
|
|
10
|
+
/**
|
|
11
|
+
* Which role the detached child runs (Phase 3). Absent ⇒ `'exec'`, so every
|
|
12
|
+
* pre-Phase-3 caller and every faked spawner in the existing tests keeps its
|
|
13
|
+
* exact meaning.
|
|
14
|
+
*
|
|
15
|
+
* - `'exec'` — a COMMAND order; the child runs `owenloop work exec`.
|
|
16
|
+
* - `'agent-run'` — an AGENT order; the child runs `owenloop work agent-run` and
|
|
17
|
+
* hosts the step agent itself. This is the ONLY agent path.
|
|
18
|
+
*/
|
|
19
|
+
kind?: 'exec' | 'agent-run';
|
|
20
|
+
/**
|
|
21
|
+
* The harness id to host the step agent in, for `kind: 'agent-run'` only.
|
|
22
|
+
* Absent carries no `--harness` flag, leaving the child to resolve the id
|
|
23
|
+
* from `OWENLOOP_HARNESS`, the step def, or its built-in default. Ignored for
|
|
24
|
+
* `'exec'` (a command order has no step agent).
|
|
25
|
+
*/
|
|
26
|
+
harness?: string;
|
|
27
|
+
}
|
|
28
|
+
/** The result the loop records: the child's pid. */
|
|
29
|
+
export interface SpawnResult {
|
|
30
|
+
pid: number;
|
|
31
|
+
}
|
|
32
|
+
/** The spawn seam. Injected; faked in tests. */
|
|
33
|
+
export type Spawner = (spec: SpawnSpec) => SpawnResult;
|
|
34
|
+
/** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
|
|
35
|
+
export interface SpawnPlan {
|
|
36
|
+
command: string;
|
|
37
|
+
args: string[];
|
|
38
|
+
options: {
|
|
39
|
+
detached: true;
|
|
40
|
+
stdio: 'ignore';
|
|
41
|
+
env: NodeJS.ProcessEnv;
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Resolve the single packaged `bin/owenloop.mjs` from this module's URL.
|
|
46
|
+
*
|
|
47
|
+
* Source-driven tests import `packages/work/src/**`, while installed/runtime
|
|
48
|
+
* execution imports `dist/packages/work/src/**`; those layouts are one parent
|
|
49
|
+
* level apart. Choose the existing candidate so detached children use the root
|
|
50
|
+
* binary in both layouts.
|
|
51
|
+
*/
|
|
52
|
+
export declare function resolveOwenloopBin(): string;
|
|
53
|
+
/**
|
|
54
|
+
* Build the argv + options for a detached
|
|
55
|
+
* `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
|
|
56
|
+
* tests assert the shape without launching anything. Runs the bin under the
|
|
57
|
+
* current Node (`execPath`), matching the `owenloop work exec <order-id>` arg contract
|
|
58
|
+
* (the composite `<workflow>/<run>` carries both ids in one positional).
|
|
59
|
+
*
|
|
60
|
+
* The account is NOT an argv flag — it rides `options.env.OWENLOOP_ACCOUNT`.
|
|
61
|
+
* `env` starts from `process.env` so the detached child keeps the parent's
|
|
62
|
+
* environment inheritance (which is otherwise implicit when `env` is unset),
|
|
63
|
+
* then sets the resolved account on top.
|
|
64
|
+
*
|
|
65
|
+
* `shiftId` (W7, trailing — after `execPath` so existing positional
|
|
66
|
+
* callers are unaffected), when non-empty, appends `--shift <cid>` so the
|
|
67
|
+
* spawned `owenloop work exec` child self-declares which Shift dispatched it
|
|
68
|
+
* (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
|
|
69
|
+
*
|
|
70
|
+
* Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
|
|
71
|
+
* selects the role positional (`exec` vs `agent-run`) and `spec.harness`
|
|
72
|
+
* appends `--harness <id>` on the `agent-run` branch. Everything else — the
|
|
73
|
+
* composite order positional, `--origin`, `--shift`, and every spawn option
|
|
74
|
+
* — is identical for both kinds, so an agent-run child is detached,
|
|
75
|
+
* stdio-ignored, and account-scoped exactly like an exec child.
|
|
76
|
+
*/
|
|
77
|
+
export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string): SpawnPlan;
|
|
78
|
+
/**
|
|
79
|
+
* The default detached spawner. Captures the resolved hub `origin`, the
|
|
80
|
+
* resolved `account`, the packaged bin path, and the dispatching Shift's
|
|
81
|
+
* `shiftId` once at construction; each spawn threads them into the
|
|
82
|
+
* child's argv + spawn env. `execPath` is passed explicitly (rather than
|
|
83
|
+
* relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
|
|
84
|
+
* — can be supplied positionally.
|
|
85
|
+
*/
|
|
86
|
+
export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string): Spawner;
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The detached-exec spawn seam (plan decision 6).
|
|
3
|
+
*
|
|
4
|
+
* Every order the shift dispatches becomes a DETACHED
|
|
5
|
+
* `owenloop work exec <workflow>/<run> --origin <url>` child: `detached: true`,
|
|
6
|
+
* `stdio: 'ignore'`, `unref()` — so the child is its own process-group leader and
|
|
7
|
+
* survives the parent's death (SP5-verified kernel reparenting). The shift meters
|
|
8
|
+
* and hands off; the child self-leases (C5). Both ids ride the argv as the
|
|
9
|
+
* composite `<workflow>/<run>` order-id `owenloop work exec` parses, and `--origin`
|
|
10
|
+
* is passed through so the detached child reaches the SAME hub the shift is
|
|
11
|
+
* parked at without re-reading settings. The shift-resolved account rides the
|
|
12
|
+
* child's spawn ENV as `OWENLOOP_ACCOUNT` (exec has no `--as` flag — the spawn
|
|
13
|
+
* env is the contract), selecting which Scoped Identity credential slot
|
|
14
|
+
* (agent:<account>) exec reads.
|
|
15
|
+
*
|
|
16
|
+
* `Spawner` is an injected seam; unit tests always fake it and NEVER spawn a
|
|
17
|
+
* real child. The default impl's argv/option construction is factored into the
|
|
18
|
+
* pure `buildSpawnPlan` so a test can assert the exact shape as data.
|
|
19
|
+
*/
|
|
20
|
+
import { existsSync } from 'node:fs';
|
|
21
|
+
import { spawn } from 'node:child_process';
|
|
22
|
+
import { fileURLToPath } from 'node:url';
|
|
23
|
+
/**
|
|
24
|
+
* Resolve the single packaged `bin/owenloop.mjs` from this module's URL.
|
|
25
|
+
*
|
|
26
|
+
* Source-driven tests import `packages/work/src/**`, while installed/runtime
|
|
27
|
+
* execution imports `dist/packages/work/src/**`; those layouts are one parent
|
|
28
|
+
* level apart. Choose the existing candidate so detached children use the root
|
|
29
|
+
* binary in both layouts.
|
|
30
|
+
*/
|
|
31
|
+
export function resolveOwenloopBin() {
|
|
32
|
+
const candidates = [
|
|
33
|
+
new URL('../../../../bin/owenloop.mjs', import.meta.url),
|
|
34
|
+
new URL('../../../../../bin/owenloop.mjs', import.meta.url),
|
|
35
|
+
].map((url) => fileURLToPath(url));
|
|
36
|
+
return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Build the argv + options for a detached
|
|
40
|
+
* `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
|
|
41
|
+
* tests assert the shape without launching anything. Runs the bin under the
|
|
42
|
+
* current Node (`execPath`), matching the `owenloop work exec <order-id>` arg contract
|
|
43
|
+
* (the composite `<workflow>/<run>` carries both ids in one positional).
|
|
44
|
+
*
|
|
45
|
+
* The account is NOT an argv flag — it rides `options.env.OWENLOOP_ACCOUNT`.
|
|
46
|
+
* `env` starts from `process.env` so the detached child keeps the parent's
|
|
47
|
+
* environment inheritance (which is otherwise implicit when `env` is unset),
|
|
48
|
+
* then sets the resolved account on top.
|
|
49
|
+
*
|
|
50
|
+
* `shiftId` (W7, trailing — after `execPath` so existing positional
|
|
51
|
+
* callers are unaffected), when non-empty, appends `--shift <cid>` so the
|
|
52
|
+
* spawned `owenloop work exec` child self-declares which Shift dispatched it
|
|
53
|
+
* (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
|
|
54
|
+
*
|
|
55
|
+
* Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
|
|
56
|
+
* selects the role positional (`exec` vs `agent-run`) and `spec.harness`
|
|
57
|
+
* appends `--harness <id>` on the `agent-run` branch. Everything else — the
|
|
58
|
+
* composite order positional, `--origin`, `--shift`, and every spawn option
|
|
59
|
+
* — is identical for both kinds, so an agent-run child is detached,
|
|
60
|
+
* stdio-ignored, and account-scoped exactly like an exec child.
|
|
61
|
+
*/
|
|
62
|
+
export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId) {
|
|
63
|
+
const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
|
|
64
|
+
return {
|
|
65
|
+
command: execPath,
|
|
66
|
+
args: [
|
|
67
|
+
binPath,
|
|
68
|
+
'work',
|
|
69
|
+
role,
|
|
70
|
+
`${spec.workflow}/${spec.run}`,
|
|
71
|
+
'--origin',
|
|
72
|
+
origin,
|
|
73
|
+
...(shiftId !== undefined && shiftId !== '' ? ['--shift', shiftId] : []),
|
|
74
|
+
...(role === 'agent-run' && spec.harness !== undefined && spec.harness !== ''
|
|
75
|
+
? ['--harness', spec.harness]
|
|
76
|
+
: []),
|
|
77
|
+
],
|
|
78
|
+
options: { detached: true, stdio: 'ignore', env: { ...process.env, OWENLOOP_ACCOUNT: account } },
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* The default detached spawner. Captures the resolved hub `origin`, the
|
|
83
|
+
* resolved `account`, the packaged bin path, and the dispatching Shift's
|
|
84
|
+
* `shiftId` once at construction; each spawn threads them into the
|
|
85
|
+
* child's argv + spawn env. `execPath` is passed explicitly (rather than
|
|
86
|
+
* relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
|
|
87
|
+
* — can be supplied positionally.
|
|
88
|
+
*/
|
|
89
|
+
export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId) {
|
|
90
|
+
return (spec) => {
|
|
91
|
+
const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId);
|
|
92
|
+
const child = spawn(plan.command, plan.args, plan.options);
|
|
93
|
+
child.unref();
|
|
94
|
+
if (child.pid === undefined) {
|
|
95
|
+
const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
|
|
96
|
+
throw new Error(`spawn of 'owenloop work ${role} ${spec.workflow}/${spec.run}' returned no pid`);
|
|
97
|
+
}
|
|
98
|
+
return { pid: child.pid };
|
|
99
|
+
};
|
|
100
|
+
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/** One dispatched order the shift meters against capacity.
|
|
2
|
+
*
|
|
3
|
+
* Two kinds, and BOTH are real local processes tracked by a live pid:
|
|
4
|
+
* - `exec` (default; absent `kind` for legacy records) — a detached
|
|
5
|
+
* `owenloop work exec` command child, tracked by `kill(pid, 0)`.
|
|
6
|
+
* - `agent-run` — a detached `owenloop work agent-run` child hosting the step
|
|
7
|
+
* agent itself, tracked exactly the same way.
|
|
8
|
+
*
|
|
9
|
+
* There is no pid-less kind any more. The removed `'agent'` kind recorded a
|
|
10
|
+
* stamped Step Agent file handed to an out-of-process Shift: no local
|
|
11
|
+
* child, a `0` sentinel pid, and a coarse TTL standing in for liveness. With
|
|
12
|
+
* the stamp path gone nothing produces such a record, so a leftover one on disk
|
|
13
|
+
* fails the pid probe and is reaped on the next reconcile — which is correct.
|
|
14
|
+
*
|
|
15
|
+
* `def/hash/step` are dispatch provenance (which cached def revision and step
|
|
16
|
+
* this child was dispatched for); they are absent for command orders. */
|
|
17
|
+
export interface ChildRecord {
|
|
18
|
+
workflow: string;
|
|
19
|
+
run: string;
|
|
20
|
+
/** The child's live pid. */
|
|
21
|
+
pid: number;
|
|
22
|
+
spawnedAt: number;
|
|
23
|
+
/** Dispatch kind; absent = `'exec'` (back-compat with pre-split records). */
|
|
24
|
+
kind?: 'exec' | 'agent-run';
|
|
25
|
+
def?: string;
|
|
26
|
+
hash?: string;
|
|
27
|
+
step?: string;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Resolve the state dir: `override` → `$XDG_STATE_HOME/owenloop/exec` →
|
|
31
|
+
* `$HOME/.local/state/owenloop/exec`. Throws when none is available (same
|
|
32
|
+
* stance as the cache/settings resolvers — never guess a home dir). Tests pass
|
|
33
|
+
* an explicit `override` pointing at a temp dir.
|
|
34
|
+
*/
|
|
35
|
+
export declare function resolveStateDir(env: Record<string, string | undefined>, override?: string): string;
|
|
36
|
+
/** Persist a child record (atomic temp+rename). Fail-open. */
|
|
37
|
+
export declare function writeChildRecord(stateDir: string, rec: ChildRecord): void;
|
|
38
|
+
/** Read every child record in the state dir. Corrupt files are skipped, a
|
|
39
|
+
* missing dir reads as empty. Fail-open. */
|
|
40
|
+
export declare function readChildRecords(stateDir: string): ChildRecord[];
|
|
41
|
+
/** Delete a child record by run id. Fail-open. */
|
|
42
|
+
export declare function removeChildRecord(stateDir: string, run: string): void;
|
|
43
|
+
/** A liveness probe over a pid. Injectable so tests never touch real pids. */
|
|
44
|
+
export type Liveness = (pid: number) => boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Default liveness probe: `process.kill(pid, 0)` sends no signal, only checks
|
|
47
|
+
* existence/permissions. `ESRCH` ⇒ the process is gone (dead). `EPERM` ⇒ it
|
|
48
|
+
* exists but is owned by another user (count as alive — pid reuse aside, a live
|
|
49
|
+
* foreign process at that pid is not ours to reap). Any other error ⇒ alive
|
|
50
|
+
* (conservative: don't reap on an ambiguous signal).
|
|
51
|
+
*/
|
|
52
|
+
export declare const defaultIsAlive: Liveness;
|
|
53
|
+
export interface Reconciliation {
|
|
54
|
+
/** Records whose child is still alive — these count as in-flight. */
|
|
55
|
+
live: ChildRecord[];
|
|
56
|
+
/** Records whose child is gone — reaped (record deleted) this pass. */
|
|
57
|
+
reaped: ChildRecord[];
|
|
58
|
+
}
|
|
59
|
+
/** Injectable knobs for `reconcileInFlight` (all optional; real defaults). */
|
|
60
|
+
export interface ReconcileOptions {
|
|
61
|
+
/** pid liveness probe (default `defaultIsAlive`). */
|
|
62
|
+
isAlive?: Liveness;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Scan the state dir, decide each record's liveness, delete the dead ones, and
|
|
66
|
+
* return the live/reaped split. Deduped by run id (last record for a run wins)
|
|
67
|
+
* so a stray double-write can never double-count capacity.
|
|
68
|
+
*
|
|
69
|
+
* Liveness is UNIFORM: every record names a real local child, so every record
|
|
70
|
+
* is live exactly while `kill(pid, 0)` says its pid is.
|
|
71
|
+
*
|
|
72
|
+
* Back-compat: the second positional arg still accepts a bare `Liveness`
|
|
73
|
+
* (pre-split callers passed `reconcileInFlight(dir, isAlive)`).
|
|
74
|
+
*/
|
|
75
|
+
export declare function reconcileInFlight(stateDir: string, arg?: Liveness | ReconcileOptions): Reconciliation;
|
|
76
|
+
/** Ensure the state dir exists so the first read doesn't churn. Fail-open. */
|
|
77
|
+
export declare function ensureStateDir(stateDir: string): void;
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* In-flight tracking for detached exec children (plan decision 7).
|
|
3
|
+
*
|
|
4
|
+
* The shift spawns `owenloop work exec <run>` DETACHED — the child survives a shift
|
|
5
|
+
* restart (kernel reparenting, SP5-verified). So the shift cannot trust its own
|
|
6
|
+
* memory to know what is in flight across a restart; it reconstructs that from
|
|
7
|
+
* durable local records instead. A state dir holds one JSON record per spawned
|
|
8
|
+
* child — `{ workflow, run, pid, spawnedAt, def?, hash?, step? }` — and on every
|
|
9
|
+
* sweep (and startup) we scan the records, probe each pid with `kill(pid, 0)`,
|
|
10
|
+
* count the live ones as in-flight, and reap the dead ones.
|
|
11
|
+
*
|
|
12
|
+
* The design docs disdain PID files for broker/discovery plumbing of
|
|
13
|
+
* harness-managed processes; these are shift-spawned children, so local
|
|
14
|
+
* bookkeeping is the legitimate mechanism, not that anti-pattern. Metering off
|
|
15
|
+
* this count is an EFFICIENCY mechanism only — engine race-safety plus the
|
|
16
|
+
* pickup/lease TTLs are the correctness backstop — so a rare pid-reuse miscount
|
|
17
|
+
* is acceptable and never a bug to chase.
|
|
18
|
+
*
|
|
19
|
+
* Every fs op is FAIL-OPEN: a broken state dir degrades metering (the shift may
|
|
20
|
+
* over- or under-count in flight), it never kills the loop.
|
|
21
|
+
*/
|
|
22
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
23
|
+
import { join } from 'node:path';
|
|
24
|
+
/**
|
|
25
|
+
* Resolve the state dir: `override` → `$XDG_STATE_HOME/owenloop/exec` →
|
|
26
|
+
* `$HOME/.local/state/owenloop/exec`. Throws when none is available (same
|
|
27
|
+
* stance as the cache/settings resolvers — never guess a home dir). Tests pass
|
|
28
|
+
* an explicit `override` pointing at a temp dir.
|
|
29
|
+
*/
|
|
30
|
+
export function resolveStateDir(env, override) {
|
|
31
|
+
if (override !== undefined && override.trim() !== '')
|
|
32
|
+
return override;
|
|
33
|
+
const xdg = env['XDG_STATE_HOME'];
|
|
34
|
+
if (xdg !== undefined && xdg.trim() !== '')
|
|
35
|
+
return join(xdg, 'owenloop', 'exec');
|
|
36
|
+
const home = env['HOME'];
|
|
37
|
+
if (home !== undefined && home.trim() !== '')
|
|
38
|
+
return join(home, '.local', 'state', 'owenloop', 'exec');
|
|
39
|
+
throw new Error('cannot locate a state directory: set OWENLOOP_STATE_DIR, XDG_STATE_HOME, or HOME');
|
|
40
|
+
}
|
|
41
|
+
/** Map a run id onto a safe record filename (hub run ids are already safe; this
|
|
42
|
+
* is defense in depth against a `/`, `\`, or `..` sneaking in). */
|
|
43
|
+
function recordFile(stateDir, run) {
|
|
44
|
+
const safe = run.replace(/[^A-Za-z0-9_.-]/g, '_');
|
|
45
|
+
return join(stateDir, `${safe}.json`);
|
|
46
|
+
}
|
|
47
|
+
/** Persist a child record (atomic temp+rename). Fail-open. */
|
|
48
|
+
export function writeChildRecord(stateDir, rec) {
|
|
49
|
+
try {
|
|
50
|
+
mkdirSync(stateDir, { recursive: true });
|
|
51
|
+
const file = recordFile(stateDir, rec.run);
|
|
52
|
+
const tmp = join(stateDir, `.${Math.random().toString(36).slice(2)}-${process.pid}-${Date.now()}.tmp`);
|
|
53
|
+
writeFileSync(tmp, JSON.stringify(rec));
|
|
54
|
+
try {
|
|
55
|
+
renameSync(tmp, file);
|
|
56
|
+
}
|
|
57
|
+
catch (err) {
|
|
58
|
+
try {
|
|
59
|
+
unlinkSync(tmp);
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
// best-effort cleanup
|
|
63
|
+
}
|
|
64
|
+
throw err;
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
// fail-open: a lost record degrades metering, never kills the loop.
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
/** Read every child record in the state dir. Corrupt files are skipped, a
|
|
72
|
+
* missing dir reads as empty. Fail-open. */
|
|
73
|
+
export function readChildRecords(stateDir) {
|
|
74
|
+
let names;
|
|
75
|
+
try {
|
|
76
|
+
names = readdirSync(stateDir).filter((f) => f.endsWith('.json'));
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return [];
|
|
80
|
+
}
|
|
81
|
+
const records = [];
|
|
82
|
+
for (const name of names) {
|
|
83
|
+
try {
|
|
84
|
+
const rec = JSON.parse(readFileSync(join(stateDir, name), 'utf8'));
|
|
85
|
+
if (rec && typeof rec.run === 'string' && typeof rec.pid === 'number' && typeof rec.workflow === 'string') {
|
|
86
|
+
records.push(rec);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
// skip corrupt record
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
return records;
|
|
94
|
+
}
|
|
95
|
+
/** Delete a child record by run id. Fail-open. */
|
|
96
|
+
export function removeChildRecord(stateDir, run) {
|
|
97
|
+
try {
|
|
98
|
+
rmSync(recordFile(stateDir, run), { force: true });
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
// best-effort
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Default liveness probe: `process.kill(pid, 0)` sends no signal, only checks
|
|
106
|
+
* existence/permissions. `ESRCH` ⇒ the process is gone (dead). `EPERM` ⇒ it
|
|
107
|
+
* exists but is owned by another user (count as alive — pid reuse aside, a live
|
|
108
|
+
* foreign process at that pid is not ours to reap). Any other error ⇒ alive
|
|
109
|
+
* (conservative: don't reap on an ambiguous signal).
|
|
110
|
+
*/
|
|
111
|
+
export const defaultIsAlive = (pid) => {
|
|
112
|
+
if (!Number.isInteger(pid) || pid <= 0)
|
|
113
|
+
return false;
|
|
114
|
+
try {
|
|
115
|
+
process.kill(pid, 0);
|
|
116
|
+
return true;
|
|
117
|
+
}
|
|
118
|
+
catch (err) {
|
|
119
|
+
return err.code !== 'ESRCH';
|
|
120
|
+
}
|
|
121
|
+
};
|
|
122
|
+
/**
|
|
123
|
+
* Scan the state dir, decide each record's liveness, delete the dead ones, and
|
|
124
|
+
* return the live/reaped split. Deduped by run id (last record for a run wins)
|
|
125
|
+
* so a stray double-write can never double-count capacity.
|
|
126
|
+
*
|
|
127
|
+
* Liveness is UNIFORM: every record names a real local child, so every record
|
|
128
|
+
* is live exactly while `kill(pid, 0)` says its pid is.
|
|
129
|
+
*
|
|
130
|
+
* Back-compat: the second positional arg still accepts a bare `Liveness`
|
|
131
|
+
* (pre-split callers passed `reconcileInFlight(dir, isAlive)`).
|
|
132
|
+
*/
|
|
133
|
+
export function reconcileInFlight(stateDir, arg) {
|
|
134
|
+
const opts = typeof arg === 'function' ? { isAlive: arg } : (arg ?? {});
|
|
135
|
+
const isAlive = opts.isAlive ?? defaultIsAlive;
|
|
136
|
+
const byRun = new Map();
|
|
137
|
+
for (const rec of readChildRecords(stateDir))
|
|
138
|
+
byRun.set(rec.run, rec);
|
|
139
|
+
const live = [];
|
|
140
|
+
const reaped = [];
|
|
141
|
+
for (const rec of byRun.values()) {
|
|
142
|
+
const alive = isAlive(rec.pid);
|
|
143
|
+
if (alive) {
|
|
144
|
+
live.push(rec);
|
|
145
|
+
}
|
|
146
|
+
else {
|
|
147
|
+
removeChildRecord(stateDir, rec.run);
|
|
148
|
+
reaped.push(rec);
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
return { live, reaped };
|
|
152
|
+
}
|
|
153
|
+
/** Ensure the state dir exists so the first read doesn't churn. Fail-open. */
|
|
154
|
+
export function ensureStateDir(stateDir) {
|
|
155
|
+
try {
|
|
156
|
+
if (!existsSync(stateDir))
|
|
157
|
+
mkdirSync(stateDir, { recursive: true });
|
|
158
|
+
}
|
|
159
|
+
catch {
|
|
160
|
+
// fail-open
|
|
161
|
+
}
|
|
162
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Single source of the CLI usage text. Printed by `--help`/`help` (to stdout,
|
|
3
|
+
* exit 0) and on a dispatch error (to stderr, exit 2). Keeping it in one place
|
|
4
|
+
* means the help output and the error output never drift apart.
|
|
5
|
+
*/
|
|
6
|
+
export declare const USAGE = "owenloop work \u2014 execution-side CLI companion to owenloop\n\nUsage:\n owenloop work hold --order <id> [options] hold an order with a heartbeating lease\n owenloop work exec <order-id> [options] run a command order in a self-leasing loop\n owenloop work agent-run <order-id> [options] host an agent order's step agent in a\n harness, in a self-leasing loop\n owenloop work prepare <workflow> [--origin <url>]\n fetch, cache & normalize step specs\n owenloop work lint <workflow-name | path> lint x.harness option bags in a def\n owenloop work sessions [--all] [--json] list this machine's recorded harness\n sessions and how to re-open them\n owenloop work release --session <id> [options] drain a session's held claims\n owenloop work settings print the resolved settings file\n owenloop work join <code> [--hub <origin>] [--as <account>]\n redeem a join code and store the Scoped\n Identity credential (one-time provisioning)\n\nOptions:\n -h, --help show this help and exit 0\n --version print the owenloop work version and exit 0\n\n root shift options (run as owenloop shift start <crew...> | --all):\n <crew...> serve only these crews (positional, space\n separated); or --all for every crew on the key\n --all serve every crew on the key\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account to read + hand\n to dispatched holds/execs (default 'default')\n --name <n> Shift name (default <hostname>/<cwd>)\n --cap <n> max in-flight exec children (default 3)\n --poll-interval <ms> wake poll cadence (default 5000)\n --once bootstrap wake + one sweep, then exit (demo/e2e)\n --max-agents <n> max in-flight agent-run children, separate from\n --cap (default 4; else settings.maxConcurrentAgents)\n --cache-dir/--state-dir <p> override the resolved dirs\n\n hold options:\n --order <workflow>/<run> the order to hold (or --order <run> --workflow)\n --workflow <wf> required when --order is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account (default\n 'default'; the shift stamps this into born-bound\n holds)\n --session <id> session-holder tag (else env OWENLOOP_SESSION;\n else an anon:<hostname>:<pid> fallback \u2014 a\n holder is always sent)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --ignore-stdin don't final-breath on stdin EOF (detached use)\n --mcp run as a stdio-MCP work-holder: tools get_order /\n submit, lease kept warm underneath (mutually\n exclusive with --ignore-stdin \u2014 stdin is the\n transport)\n\n exec options (usually spawned by shift, not run by hand):\n <workflow>/<run> the command order to run (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n\n agent-run options (spawned by the shift, not run by hand):\n <workflow>/<run> the agent order to host (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --harness <id> which registered harness hosts the step agent\n (else env OWENLOOP_HARNESS, else the step def's\n 'harness' field, else the first registered one)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --submit-grace <ms> after the turn ends, how long to keep asking the\n hub whether the agent's submit landed (default\n 15000). Task completion comes from the HUB, never\n from the harness stream.\n --confirm-interval <ms> poll cadence inside that grace (default 1000)\n\n release options:\n --session <id> session whose claims to drain (else env\n OWENLOOP_SESSION). Agent-held claims re-offer;\n exec-held claims are drain-exempt (B3).\n --origin <url> hub origin (else settings.hubOrigin)\n\n settings (no options in v1):\n prints the resolved settings file path, whether it exists, each known\n knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,\n maxConcurrentAgents, workRoot, workRepo) with its value + provenance,\n and any unrecognized keys.\n settings.dispatchCap/stateDir are the lowest-precedence\n fallbacks for shift's --cap/--state-dir. NO secrets ever\n live in settings \u2014 credentials stay in owenloop's own store.\n\n sessions options:\n --all include 'dead' sessions (hidden by default \u2014\n a dead session can no longer be resumed)\n --json print the raw newest-per-step records, tokens\n included, instead of the table\n --cache-dir <p> override the resolved cache dir\n\n join options:\n --hub <origin> hub to redeem against (else settings.hubOrigin;\n one of the two is REQUIRED \u2014 the code never\n chooses the hub)\n --as <account> credential account to store under (default:\n the Scoped Identity name the hub returns)\n\n shift/hold/exec/prepare/release env:\n credentials come from owenloop's store \u2014 each role reads the\n agent:<account> slot for its origin (never the human slot); a\n missing slot refuses with a runnable 'owenloop login' command.\n OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release\n (default 'default'; shift uses --as, and\n stamps it onto dispatched holds/execs)\n OWENLOOP_TOKEN dev-only bearer override \u2014 when set, used\n verbatim and the store + account are\n bypassed (NOT the primary path)\n OWENLOOP_CACHE_DIR cache root\n OWENLOOP_STATE_DIR shift in-flight state dir\n OWENLOOP_SESSION hold session-holder tag / release drain target\n OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for\n hold/exec/agent-run's --shift (advisory\n only, never for auth/routing/dispatch)\n OWENLOOP_HARNESS agent-run harness id; below --harness, above\n the step def's 'harness' field\n OWENLOOP_WORK_ROOT root for per-RUN agent work dirs\n (<workRoot>/<workflow>/<run>); above\n settings.workRoot, default <cacheDir>/work.\n A hub-supplied OrderPacket.workdir still\n wins, and is never reaped.\n OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from\n as worktrees instead of plain dirs; above\n settings.workRepo, default off\n\n Credentials / accounts:\n owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY\n over owenloop's credential store \u2014 they never write credentials. Each\n role reads the agent:<account> slot for its origin (never the human\n slot); the account defaults to 'default'. 'owenloop work join' is the one\n deliberate provisioning-time writer: it stores the Scoped Identity token a hub\n redeem returns via owenloop's public storeCredential, once, at join time\n \u2014 not a runtime write.\n store / connect an account (run owenloop; owenloop work never writes it):\n owenloop login --hub <origin> --as agent:<account>\n (use --as agent for the default account)\n or provision a fresh box from a hub-issued join code:\n owenloop work join <code> --hub <origin>\n select an account at run time:\n --as <account> on shift / hold\n OWENLOOP_ACCOUNT on exec / prepare / release\n (shift resolves once and threads both channels)\n owenloop work does NOT list stored accounts \u2014 enumerating an origin's accounts\n is an owenloop-side capability; check owenloop for which slots are stored.\n\nExit codes:\n 0 success / help / version / lint clean or warnings-only\n 1 runtime failure (fetch/hub error, cache write) / lint found an error\n 2 usage error (unknown or missing role, missing required arg)\n 3 role not implemented yet (skeleton stub \u2014 lands in a later delivery)\n";
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Single source of the CLI usage text. Printed by `--help`/`help` (to stdout,
|
|
3
|
+
* exit 0) and on a dispatch error (to stderr, exit 2). Keeping it in one place
|
|
4
|
+
* means the help output and the error output never drift apart.
|
|
5
|
+
*/
|
|
6
|
+
export const USAGE = `owenloop work — execution-side CLI companion to owenloop
|
|
7
|
+
|
|
8
|
+
Usage:
|
|
9
|
+
owenloop work hold --order <id> [options] hold an order with a heartbeating lease
|
|
10
|
+
owenloop work exec <order-id> [options] run a command order in a self-leasing loop
|
|
11
|
+
owenloop work agent-run <order-id> [options] host an agent order's step agent in a
|
|
12
|
+
harness, in a self-leasing loop
|
|
13
|
+
owenloop work prepare <workflow> [--origin <url>]
|
|
14
|
+
fetch, cache & normalize step specs
|
|
15
|
+
owenloop work lint <workflow-name | path> lint x.harness option bags in a def
|
|
16
|
+
owenloop work sessions [--all] [--json] list this machine's recorded harness
|
|
17
|
+
sessions and how to re-open them
|
|
18
|
+
owenloop work release --session <id> [options] drain a session's held claims
|
|
19
|
+
owenloop work settings print the resolved settings file
|
|
20
|
+
owenloop work join <code> [--hub <origin>] [--as <account>]
|
|
21
|
+
redeem a join code and store the Scoped
|
|
22
|
+
Identity credential (one-time provisioning)
|
|
23
|
+
|
|
24
|
+
Options:
|
|
25
|
+
-h, --help show this help and exit 0
|
|
26
|
+
--version print the owenloop work version and exit 0
|
|
27
|
+
|
|
28
|
+
root shift options (run as owenloop shift start <crew...> | --all):
|
|
29
|
+
<crew...> serve only these crews (positional, space
|
|
30
|
+
separated); or --all for every crew on the key
|
|
31
|
+
--all serve every crew on the key
|
|
32
|
+
--origin <url> hub origin (else settings.hubOrigin)
|
|
33
|
+
--as <account> Scoped Identity credential account to read + hand
|
|
34
|
+
to dispatched holds/execs (default 'default')
|
|
35
|
+
--name <n> Shift name (default <hostname>/<cwd>)
|
|
36
|
+
--cap <n> max in-flight exec children (default 3)
|
|
37
|
+
--poll-interval <ms> wake poll cadence (default 5000)
|
|
38
|
+
--once bootstrap wake + one sweep, then exit (demo/e2e)
|
|
39
|
+
--max-agents <n> max in-flight agent-run children, separate from
|
|
40
|
+
--cap (default 4; else settings.maxConcurrentAgents)
|
|
41
|
+
--cache-dir/--state-dir <p> override the resolved dirs
|
|
42
|
+
|
|
43
|
+
hold options:
|
|
44
|
+
--order <workflow>/<run> the order to hold (or --order <run> --workflow)
|
|
45
|
+
--workflow <wf> required when --order is a bare run id
|
|
46
|
+
--origin <url> hub origin (else settings.hubOrigin)
|
|
47
|
+
--as <account> Scoped Identity credential account (default
|
|
48
|
+
'default'; the shift stamps this into born-bound
|
|
49
|
+
holds)
|
|
50
|
+
--session <id> session-holder tag (else env OWENLOOP_SESSION;
|
|
51
|
+
else an anon:<hostname>:<pid> fallback — a
|
|
52
|
+
holder is always sent)
|
|
53
|
+
--shift <id> dispatching Shift's self-declared id (else
|
|
54
|
+
env OWENLOOP_SHIFT_ID); advisory only
|
|
55
|
+
--heartbeat-interval <ms> lease renew cadence (default 60000)
|
|
56
|
+
--jump-tolerance <ms> wall-gap slack before a tick is treated as a
|
|
57
|
+
clock jump / laptop sleep (default 30000)
|
|
58
|
+
--ignore-stdin don't final-breath on stdin EOF (detached use)
|
|
59
|
+
--mcp run as a stdio-MCP work-holder: tools get_order /
|
|
60
|
+
submit, lease kept warm underneath (mutually
|
|
61
|
+
exclusive with --ignore-stdin — stdin is the
|
|
62
|
+
transport)
|
|
63
|
+
|
|
64
|
+
exec options (usually spawned by shift, not run by hand):
|
|
65
|
+
<workflow>/<run> the command order to run (positional order-id;
|
|
66
|
+
or a bare <run> plus --workflow <wf>)
|
|
67
|
+
--workflow <wf> required when the order-id is a bare run id
|
|
68
|
+
--origin <url> hub origin (else settings.hubOrigin)
|
|
69
|
+
--shift <id> dispatching Shift's self-declared id (else
|
|
70
|
+
env OWENLOOP_SHIFT_ID); advisory only
|
|
71
|
+
--heartbeat-interval <ms> lease renew cadence (default 60000)
|
|
72
|
+
--jump-tolerance <ms> wall-gap slack before a tick is treated as a
|
|
73
|
+
clock jump / laptop sleep (default 30000)
|
|
74
|
+
|
|
75
|
+
agent-run options (spawned by the shift, not run by hand):
|
|
76
|
+
<workflow>/<run> the agent order to host (positional order-id;
|
|
77
|
+
or a bare <run> plus --workflow <wf>)
|
|
78
|
+
--workflow <wf> required when the order-id is a bare run id
|
|
79
|
+
--origin <url> hub origin (else settings.hubOrigin)
|
|
80
|
+
--harness <id> which registered harness hosts the step agent
|
|
81
|
+
(else env OWENLOOP_HARNESS, else the step def's
|
|
82
|
+
'harness' field, else the first registered one)
|
|
83
|
+
--shift <id> dispatching Shift's self-declared id (else
|
|
84
|
+
env OWENLOOP_SHIFT_ID); advisory only
|
|
85
|
+
--heartbeat-interval <ms> lease renew cadence (default 60000)
|
|
86
|
+
--jump-tolerance <ms> wall-gap slack before a tick is treated as a
|
|
87
|
+
clock jump / laptop sleep (default 30000)
|
|
88
|
+
--submit-grace <ms> after the turn ends, how long to keep asking the
|
|
89
|
+
hub whether the agent's submit landed (default
|
|
90
|
+
15000). Task completion comes from the HUB, never
|
|
91
|
+
from the harness stream.
|
|
92
|
+
--confirm-interval <ms> poll cadence inside that grace (default 1000)
|
|
93
|
+
|
|
94
|
+
release options:
|
|
95
|
+
--session <id> session whose claims to drain (else env
|
|
96
|
+
OWENLOOP_SESSION). Agent-held claims re-offer;
|
|
97
|
+
exec-held claims are drain-exempt (B3).
|
|
98
|
+
--origin <url> hub origin (else settings.hubOrigin)
|
|
99
|
+
|
|
100
|
+
settings (no options in v1):
|
|
101
|
+
prints the resolved settings file path, whether it exists, each known
|
|
102
|
+
knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,
|
|
103
|
+
maxConcurrentAgents, workRoot, workRepo) with its value + provenance,
|
|
104
|
+
and any unrecognized keys.
|
|
105
|
+
settings.dispatchCap/stateDir are the lowest-precedence
|
|
106
|
+
fallbacks for shift's --cap/--state-dir. NO secrets ever
|
|
107
|
+
live in settings — credentials stay in owenloop's own store.
|
|
108
|
+
|
|
109
|
+
sessions options:
|
|
110
|
+
--all include 'dead' sessions (hidden by default —
|
|
111
|
+
a dead session can no longer be resumed)
|
|
112
|
+
--json print the raw newest-per-step records, tokens
|
|
113
|
+
included, instead of the table
|
|
114
|
+
--cache-dir <p> override the resolved cache dir
|
|
115
|
+
|
|
116
|
+
join options:
|
|
117
|
+
--hub <origin> hub to redeem against (else settings.hubOrigin;
|
|
118
|
+
one of the two is REQUIRED — the code never
|
|
119
|
+
chooses the hub)
|
|
120
|
+
--as <account> credential account to store under (default:
|
|
121
|
+
the Scoped Identity name the hub returns)
|
|
122
|
+
|
|
123
|
+
shift/hold/exec/prepare/release env:
|
|
124
|
+
credentials come from owenloop's store — each role reads the
|
|
125
|
+
agent:<account> slot for its origin (never the human slot); a
|
|
126
|
+
missing slot refuses with a runnable 'owenloop login' command.
|
|
127
|
+
OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release
|
|
128
|
+
(default 'default'; shift uses --as, and
|
|
129
|
+
stamps it onto dispatched holds/execs)
|
|
130
|
+
OWENLOOP_TOKEN dev-only bearer override — when set, used
|
|
131
|
+
verbatim and the store + account are
|
|
132
|
+
bypassed (NOT the primary path)
|
|
133
|
+
OWENLOOP_CACHE_DIR cache root
|
|
134
|
+
OWENLOOP_STATE_DIR shift in-flight state dir
|
|
135
|
+
OWENLOOP_SESSION hold session-holder tag / release drain target
|
|
136
|
+
OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for
|
|
137
|
+
hold/exec/agent-run's --shift (advisory
|
|
138
|
+
only, never for auth/routing/dispatch)
|
|
139
|
+
OWENLOOP_HARNESS agent-run harness id; below --harness, above
|
|
140
|
+
the step def's 'harness' field
|
|
141
|
+
OWENLOOP_WORK_ROOT root for per-RUN agent work dirs
|
|
142
|
+
(<workRoot>/<workflow>/<run>); above
|
|
143
|
+
settings.workRoot, default <cacheDir>/work.
|
|
144
|
+
A hub-supplied OrderPacket.workdir still
|
|
145
|
+
wins, and is never reaped.
|
|
146
|
+
OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from
|
|
147
|
+
as worktrees instead of plain dirs; above
|
|
148
|
+
settings.workRepo, default off
|
|
149
|
+
|
|
150
|
+
Credentials / accounts:
|
|
151
|
+
owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY
|
|
152
|
+
over owenloop's credential store — they never write credentials. Each
|
|
153
|
+
role reads the agent:<account> slot for its origin (never the human
|
|
154
|
+
slot); the account defaults to 'default'. 'owenloop work join' is the one
|
|
155
|
+
deliberate provisioning-time writer: it stores the Scoped Identity token a hub
|
|
156
|
+
redeem returns via owenloop's public storeCredential, once, at join time
|
|
157
|
+
— not a runtime write.
|
|
158
|
+
store / connect an account (run owenloop; owenloop work never writes it):
|
|
159
|
+
owenloop login --hub <origin> --as agent:<account>
|
|
160
|
+
(use --as agent for the default account)
|
|
161
|
+
or provision a fresh box from a hub-issued join code:
|
|
162
|
+
owenloop work join <code> --hub <origin>
|
|
163
|
+
select an account at run time:
|
|
164
|
+
--as <account> on shift / hold
|
|
165
|
+
OWENLOOP_ACCOUNT on exec / prepare / release
|
|
166
|
+
(shift resolves once and threads both channels)
|
|
167
|
+
owenloop work does NOT list stored accounts — enumerating an origin's accounts
|
|
168
|
+
is an owenloop-side capability; check owenloop for which slots are stored.
|
|
169
|
+
|
|
170
|
+
Exit codes:
|
|
171
|
+
0 success / help / version / lint clean or warnings-only
|
|
172
|
+
1 runtime failure (fetch/hub error, cache write) / lint found an error
|
|
173
|
+
2 usage error (unknown or missing role, missing required arg)
|
|
174
|
+
3 role not implemented yet (skeleton stub — lands in a later delivery)
|
|
175
|
+
`;
|